Title: API reference Description: Authenticate and call the OpenPost HTTP API. Canonical: https://openpo.st/docs/api-reference Source: [https://openpo.st/docs/api-reference](https://openpo.st/docs/api-reference) # API reference Use the HTTP API when your own app or script needs to read OpenPost data or manage publications. Start with a token, make one read request, then use the endpoint pages for the fields and responses of the operation you need. Requests and responses use JSON. ## 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. ## Try a read 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" ``` The response lists workspaces this token can access. Use one of their IDs when an endpoint asks for a workspace ID. OpenPost checks access again on every private operation. ## Understand an error | 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 body before retrying. A successful request that queues a publication means OpenPost accepted the work; it does not mean the provider has published it. Check the publication's destination statuses for the final result. ## Find an endpoint Browse the generated endpoint pages: - [List workspaces](https://openpo.st/docs/api-reference/workspaces/list-workspaces) - [List publications](https://openpo.st/docs/api-reference/publications/list-publications) - [Create a publication](https://openpo.st/docs/api-reference/publications/create-publication) - [Schedule a publication](https://openpo.st/docs/api-reference/publications/schedule-publication) - [List connected accounts](https://openpo.st/docs/api-reference/accounts/list-accounts) The machine-readable contract is available at [`/openapi.json`](https://openpo.st/docs/openapi.json). Generate clients from that file instead of copying request or response schemas into another document. For everyday scripting, skip the raw HTTP and use the [TypeScript SDK](https://openpo.st/docs/automate/sdk).