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:

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:

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:

The machine-readable contract is available at /openapi.json. Generate clients from that file instead of copying request or response schemas into another document.