Developer overview

post.buzz exposes a versioned REST API under /api/v1/... for integrating publishing, accounts, media, inbox, analytics, teams, and imports into your own tooling. It's authenticated with API keys, returns JSON, and publishes a machine-readable OpenAPI specification.

Base URL

All REST endpoints are mounted under /api on your API origin, so the effective paths are /api/v1/.... The exact host depends on your deployment (the same origin that serves the app also serves the API).

https://<your-api-origin>/api/v1/...

OpenAPI specification

The full machine-readable spec (OpenAPI 3.1.0) is always available at:

GET https://<your-api-origin>/api/openapi.json

Use it to generate typed clients, explore schemas, or verify a field name against the version you're running. Every endpoint listed below appears in the spec.

REST vs tRPC

post.buzz's own frontend talks to the backend over tRPC at /api/trpc, which gives it end-to-end type safety. The REST API is a thinner, stable, publicly-documented surface for third-party integrations, automation scripts, and anything that isn't part of the post.buzz frontend.

	REST API	tRPC
Path	/api/v1/...	/api/trpc/...
Auth	API key (Bearer)	Session cookie
Use for	External integrations	(internal)
Stability	Versioned, documented	Fluid

Endpoint map

Every endpoint requires an API key and an active or trialing subscription — without one, every call returns 403 subscription_required.

Posts

Endpoint	Method	Purpose
/v1/posts	GET	List posts (filter by status, search q)
/v1/posts	POST	Create / schedule / cross-post (201)
/v1/posts/{id}	GET	Post detail
/v1/posts/{id}	PATCH	Update caption, schedule, accounts, poll
/v1/posts/{id}	DELETE	Delete a draft or scheduled post
/v1/posts/{id}/retry	POST	Retry a failed publish
/v1/posts/{id}/reschedule	POST	Move a scheduled post
/v1/posts/{id}/analytics	GET	Per-post insight

Accounts & platforms

Endpoint	Method	Purpose
/v1/accounts	GET	List connected accounts
/v1/accounts/connect-url	GET	Get an OAuth connect URL
/v1/accounts/{id}	GET	Account profile
/v1/accounts/{id}/refresh	POST	Refresh OAuth tokens server-side
/v1/accounts/{id}	DELETE	Disconnect an account
/v1/accounts/{id}/tools	GET	List platform tools
/v1/accounts/{id}/tools/{tool}	POST	Run reddit-flairs / pinterest-boards
/v1/platforms	GET	All platforms + capabilities
/v1/platforms/{platform}	GET	One platform's capabilities and fields

Organization, usage & diagnostics

Endpoint	Method	Purpose
/v1/organization	GET	Org, plan, limits, account counts
/v1/usage	GET	Post quota + credit balance
/v1/diagnostics/setup	GET	Connectivity/ownership/quota self-check for a key

Media

Endpoint	Method	Purpose
/v1/media	POST	Ingest media from a URL
/v1/media/upload	POST	Multipart file upload
/v1/media	GET	List media (filter by type)
/v1/media/{id}	GET	Media detail
/v1/media/{id}	DELETE	Delete media

Comments, inbox & analytics

Endpoint	Method	Purpose
/v1/comments	POST	Schedule a first comment
/v1/comments	GET	List scheduled comments
/v1/comments/{id}	GET/PATCH/DELETE	Detail / reschedule / delete (pending only)
/v1/comments/{id}/retry	POST	Retry a failed comment
/v1/inbox	GET	List inbox items (filter/slice)
/v1/inbox/{itemId}/reply	POST	Reply to an inbox item
/v1/inbox/{itemId}/replies/{replyId}	PATCH	Edit a sent reply (Facebook)
/v1/analytics/summary	GET	Latest insights per account
/v1/best-times	GET	Recommended posting times
/v1/accounts/{id}/analytics	GET	Account-level analysis
/v1/accounts/{id}/analytics/refresh	POST	Force insight refresh (rate-limited)

Teams & imports

Endpoint	Method	Purpose
/v1/teams	GET/POST	List / create teams
/v1/teams/{id}	GET/PATCH/DELETE	Detail / rename / delete (409 if in use)
/v1/teams/{id}/accounts	POST	Assign an account to a team
/v1/teams/{id}/accounts/{accountId}	DELETE	Unassign (returns to default team)
/v1/imports/posts/csv	POST	Start a CSV post-import job
/v1/imports/posts/csv	GET	List import jobs
/v1/imports/posts/csv/{id}	GET	Job summary
/v1/imports/posts/csv/{id}/rows	GET	Per-row outcomes (SUCCESS/FAILED)
/v1/imports/posts/csv/{id}/retry	POST	Retry failed rows

tip

A complete, always-current list — with request/response schemas for every route — is available from GET /api/openapi.json.

Conventions

• JSON in, JSON out. Request bodies are application/json; responses are application/json.
• Success envelope. Successful responses wrap the payload as { "data": ... }. Creating a post returns 201; every other success — including all other POST, PATCH, and DELETE — returns 200.
• Validation. Each route validates input against a schema before the handler runs; invalid input short-circuits with 400.
• Pagination. List endpoints accept limit and offset query params.
• Errors. Two documented shapes plus per-route codes — see Errors.
• Limits. Platform media limits, plan quotas, and the few real rate limits — see Limits.

Next

1. Authentication — get and use an API key.
2. REST API — conventions in depth.
3. Posts — the core endpoint.
4. Webhooks — outbound event delivery.