Skip to main content
The Postbreeze REST API exposes everything you need to drive the scheduling pipeline from outside the dashboard.
  • Base URL: https://api.postbreeze.ai/api/v1
  • Auth: Authorization: Bearer pb_live_…
  • Content type: application/json request and response bodies
  • Errors: standard HTTP status codes; bodies are { "statusCode", "code", "message", "requestId" } (see Errors)
  • Rate limits: 60 req/min burst, 1000 req/15min sustained per key (see Rate limits)

​
Workspace resolution

API keys are issued in one of two modes:
  • Full access (default) — the key can act on every workspace its owner is a member of.
  • Scoped — the key is restricted to an explicit allow-list of workspaces.
How endpoints find the workspace for each request: Derivation is enforced at the resolver layer; the server never widens a scoped key’s reach. A request to a resource that belongs to a workspace outside the key’s allow-list returns 403.

​
Endpoints in v1

​
Two body shapes for POST /posts

The post-create + post-update endpoints accept a discriminated body — send exactly one of platforms (flat) or targets (nested). Sending both returns 400 MUST_SPECIFY_EXACTLY_ONE.
  • Flat ({ content, platforms: [{ accountId }] }) — Zernio-style, recommended for most calls. Same caption for every platform.
  • Nested ({ caption, targets: [{ socialAccountId, platformOptions }] }) — full control over per-platform options, per-target media overrides, and platform-specific kind discriminators.
See Platforms → Overview for the full schema of each shape.

​
URL ingest for media

POST /media/from-url accepts a public HTTPS URL and fetches the bytes server-side. The fetch is SSRF-guarded — private IPs, link-local addresses, metadata-IMDS hostnames, and DNS-rebinding tricks are rejected. Redirects are not followed (redirect: manual). By the time the call returns, the bytes live in R2; the source URL is never re-fetched at publish time.

​
Dashboard-internal routes

A second set of routes under /api/v1/me/media/* powers the dashboard UI — they take an x-workspace-id header instead of inferring from a key. SDK and MCP callers should ignore these; they’re not part of the public surface.

​
OpenAPI spec

The full machine-readable spec lives at /openapi.json on this site and is regenerated on every Postbreeze deploy. The TypeScript SDK @postbreeze/node is generated from this spec.