Postfox API

A small REST API for managing connected accounts and scheduled posts — the same API the built-in MCP server uses, available for your own scripts and agents.

Authentication

Generate a personal API token from Settings → API access for agents (you'll need an account first). Send it as a bearer token on every request:

Authorization: Bearer pf_<your token>

A token is shown once at creation time. Generating a new one immediately invalidates the old one.

Base URL & versioning

All endpoints below live under /api/v1. This prefix is a stability guarantee — existing fields and behavior won't change under v1; a breaking change would ship as /api/v2 instead, so integrations built against v1 keep working.

Rate limits & CORS

Requests are limited to 300 per 15 minutes, per token. Limit status is reported via the standard RateLimit-* response headers.

The /api/v1 API is CORS-enabled for any origin, so it can be called directly from a browser-based tool using a token — not just server-to-server.

Endpoints

Method & path	Description
`GET /api/v1/social-accounts`	List your connected social accounts
`POST /api/v1/social-accounts`	Connect an account (`platform`, `display_name`, ...)
`DELETE /api/v1/social-accounts/:id`	Disconnect an account
`GET /api/v1/posts`	List posts — filter with `?status=` and `?social_account_id=`
`GET /api/v1/posts/:id`	Get a single post
`POST /api/v1/posts`	Create a draft or scheduled post (`social_account_id`, `content`, optional `scheduled_for`)
`PATCH /api/v1/posts/:id`	Update a post's content, status, or schedule
`DELETE /api/v1/posts/:id`	Delete a post

Example

curl https://your-postfox-host/api/v1/posts \
  -H "Authorization: Bearer pf_<your token>" \
  -H "Content-Type: application/json" \
  -d '{"social_account_id": 1, "content": "Hello from the API", "scheduled_for": "2026-08-01T12:00:00Z"}'

Errors

Errors are JSON with an error key, e.g. { "error": "not found" }. Validation failures use:

{ "error": "validation_failed", "details": { "fieldErrors": { "content": ["Required"] } } }

Prefer an agent?

Postfox ships an MCP server built on this same API — point it at your token and base URL instead of calling the endpoints directly.