API Usage

Authentication

The PostPress API uses Access Tokens to authenticate every request. You can view and manage your Access Tokens in the PostPress Dashboard. This is your API key.

Your Access Tokens carry many privileges, so keep them secure. Never share an Access Token in a publicly accessible place such as GitHub, client-side code, or chat logs.

Remember to set the base URL to the value shown on your dashboard, either in your code or directly in the interactive documentation.

Key prefixes

  • pp_live_…. Production keys, hit real accounts.
  • pp_test_…. Test keys, sandboxed traffic.
Keys are shown one time only at creation. Store them in a secret manager. Rotate immediately if a key leaks.
If custom ports are blocked in your environment, you can pass port as a query parameter and stay on the standard 443 origin, for example https://api.postpress.ai/v1/accounts?port=XXXXX.

With an SDK

Pass your Access Token to the initial configuration of the SDK. The client library then automatically attaches it to every request.

Manually

To call the API directly, include the token in an Authorization: Bearer header, or in the X-API-KEY header of your request.

Authorization: Bearer pp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Pagination

List endpoints in the PostPress API use cursor pagination. Pass limit (max 250) and cursor on each request. A paginated response returns a next_cursor value, which you send back to load the next page. When next_cursor is null, there are no more results.

{ "data": [ … ], "next_cursor": "eyJ0…" }

Idempotency

All POST and PATCH endpoints accept an Idempotency-Key header. Replays with the same key return the original response, so retries are safe.

Idempotency-Key: 2c9f8b6a-replay-me

Errors

Every error returns the same JSON envelope.

{
  "error": {
    "code": "invalid_parameters",
    "message": "One or more parameters are invalid.",
    "request_id": "0e1f3a8a-…"
  }
}

Common codes

key_missing401optional
No Authorization header was sent.
key_invalid401optional
Key not recognized.
invalid_parameters400optional
Request body or query failed validation.
not_found404optional
Resource does not exist.
rate_limited429optional
Slow down. See Rate limits below.
upstream_error502optional
Transient upstream issue. Safe to retry.

Rate limits

Each API key has a tier with a token-bucket limit.

Starter60/minoptional
Default for new keys.
Scale300/minoptional
For production traffic.
Enterpriseunmeteredoptional
Contact sales.

API Schema

PostPress follows the OpenAPI specification. The API schema is available at:

  • https://api.postpress.ai/v1/api-json
  • https://api.postpress.ai/v1/api-yaml

Import either URL into an API platform like Postman, Insomnia, or your OpenAPI tooling of choice.

Updated May 2026