Title: API reference Description: Authenticate and call the OpenPost HTTP API. Canonical: https://docs.openpo.st/api-reference Source: [https://docs.openpo.st/api-reference](https://docs.openpo.st/api-reference) # API reference Use the API to manage workspaces, accounts, media, and publications over HTTP. Requests and responses use JSON. The endpoint pages include required fields, response schemas, and examples in several languages. ## Base URL For Hosted, use `https://app.openpo.st/api/v1`. For a self-hosted instance, append `/api/v1` to your public OpenPost origin. ## Authentication Use a browser session for interactive work or a bearer API token for automation: ```http Authorization: Bearer YOUR_TOKEN ``` Create and revoke tokens in **Settings → Personal → Developer**. Choose both its permissions, such as `api:read` or `api:write`, and whether it can access the current workspace or all your workspaces. Use only the access your integration needs. Copy the token when it is created. OpenPost shows it once. Set an expiry and store it in your automation's secret store. Revoke it from the same settings page when it is no longer needed. ## First request Set `OPENPOST_TOKEN` in your shell to the token you created, then list the workspaces it can access. Replace the origin if you self-host: ```sh curl https://app.openpo.st/api/v1/workspaces \ -H "Authorization: Bearer $OPENPOST_TOKEN" \ -H "Accept: application/json" ``` Use the returned workspace ID when an operation asks for one. Workspace access is checked for every private operation. ## If a request fails | Status | What to check | | ------ | ----------------------------------------------------------------------------------------------------------------- | | `401` | Send a valid bearer token. Create a new token if it expired or was revoked. | | `403` | Check both the token's permissions and its workspace access. Some operations also depend on your account or plan. | | `404` | Check the endpoint path and resource ID. Use IDs returned by the same OpenPost instance. | | `422` | Compare the request with the endpoint schema, including required fields, formats, and allowed values. | Read the error response before retrying. A successful request that queues a publication is not proof that the provider has published it; use the publication's destination statuses to track delivery. ## Find an endpoint Browse the generated endpoint pages: - [List workspaces](https://docs.openpo.st/api-reference/workspaces/list-workspaces) - [List publications](https://docs.openpo.st/api-reference/publications/list-publications) - [Create a publication](https://docs.openpo.st/api-reference/publications/create-publication) - [Schedule a publication](https://docs.openpo.st/api-reference/publications/schedule-publication) - [List connected accounts](https://docs.openpo.st/api-reference/accounts/list-accounts) The machine-readable contract is available at [`/openapi.json`](https://docs.openpo.st/openapi.json). Generate clients from that file instead of copying request or response schemas into another document.