Freepost developer docs
Use the Freepost REST API, MCP, and agent skill to work with drafts and publish to connected social accounts.
Overview
Use REST to list hosted accounts, upload media, validate and write drafts, publish or schedule, and read delivery status.
Use remote MCP with OAuth in an interactive client, or stdio MCP with an API key in a local client. The Freepost skill supplies the workflow and platform writing guidance.
Authentication
Workspace owners create keys in Settings → API Keys. Send Authorization: Bearer <workspace API key> for REST. Use a separate key per integration with the scopes and accounts it needs.
An OAuth-capable MCP client opens Freepost sign-in and consent. Choose a workspace, its accounts, and the requested scopes you want to allow. Revoke access in Settings → Connected apps.
| Scope | Access |
|---|---|
posts:read | Read workspace posts and publications. |
posts:write | Validate, create, update, and delete drafts. |
publish:write | Publish a draft now. |
accounts:read | List authorized accounts, inspect platform rules, and read workspace usage. |
media:read | List media and read media files. |
media:write | Upload or import media. |
schedules:write | Schedule a draft and cancel a queued schedule. |
webhooks:manage | Manage webhooks and inspect their delivery logs with a workspace-wide key. |
analytics:read | Read the workspace summary through the legacy analytics tool during its deprecation window. |
REST quickstart
Connect an account in Freepost and set FREEPOST_API_KEY in your shell. These examples assume a destination that accepts text-only posts. Check platform rules, upload required media, and validate the draft before publishing.
List accounts and set ACCOUNT_ID to the destination ID.
FREEPOST_API_URL=https://freepost.io curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/accounts" \ -H "Authorization: Bearer $FREEPOST_API_KEY"Create a draft. Set a fresh DRAFT_KEY for each new draft and save the returned data.id as POST_ID.
curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/posts" \ -H "Authorization: Bearer $FREEPOST_API_KEY" \ -H 'Content-Type: application/json' \ -H "Idempotency-Key: $DRAFT_KEY" \ -d '{"content":"Hello from Freepost","targetAccounts":["'"$ACCOUNT_ID"'"]}'Publish with a fresh PUBLISH_KEY. Reuse the same key and request when retrying that call. A changed request with the same key returns 409.
curl --fail-with-body -sS -X POST "$FREEPOST_API_URL/api/v1/posts/$POST_ID/publish" \ -H "Authorization: Bearer $FREEPOST_API_KEY" \ -H "Idempotency-Key: $PUBLISH_KEY"If the result is pending, set DELIVERY_ID to data.deliveryId and poll the publication. Use the post target’s latestPublicationId when recovering a delivery from the draft.
curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/publications/$DELIVERY_ID" \ -H "Authorization: Bearer $FREEPOST_API_KEY"
MCP setup
Remote MCP over Streamable HTTP
Add this remote server URL to your MCP client, then sign in and approve access. An integration can also authenticate to this URL with a workspace API key.
https://freepost.io/api/mcpLocal stdio MCP
From a Freepost checkout, build the CLI with Node.js 22 or later. Replace the example executable path with the absolute path on your machine.
pnpm --filter @freepost/mcp buildClaude Desktop and Cursor JSON
{
"mcpServers": {
"freepost": {
"command": "node",
"args": [
"/absolute/path/to/freepost/packages/mcp/dist/server.js"
],
"env": {
"FREEPOST_API_URL": "https://freepost.io",
"FREEPOST_API_KEY": "YOUR_WORKSPACE_API_KEY"
}
}
}
}Codex config.toml
Set FREEPOST_API_KEY in the environment that starts Codex.
[mcp_servers.freepost]
command = "node"
args = ["/absolute/path/to/freepost/packages/mcp/dist/server.js"]
env_vars = ["FREEPOST_API_KEY"]
[mcp_servers.freepost.env]
FREEPOST_API_URL = "https://freepost.io"Endpoints
| Operation | Method | Path | Scope | Risk tier | Idempotency key |
|---|---|---|---|---|---|
accounts.list | GET | /api/v1/accounts | accounts:read | read | None |
usage.get | GET | /api/v1/usage | accounts:read | read | None |
platforms.rules | GET | /api/v1/platforms/rules | accounts:read | read | None |
posts.get | GET | /api/v1/posts/{id} | posts:read | read | None |
publications.get | GET | /api/v1/publications/{id} | posts:read | read | None |
media.upload | POST | /api/v1/media | media:write | draft | None |
posts.validate | POST | /api/v1/posts/validate | posts:write | draft | None |
posts.create | POST | /api/v1/posts | posts:write | draft | Required* |
posts.update | PATCH | /api/v1/posts/{id} | posts:write | draft | None |
posts.delete | DELETE | /api/v1/posts/{id} | posts:write | draft | None |
posts.publish | POST | /api/v1/posts/{id}/publish | publish:write | external | Required* |
posts.schedule | POST | /api/v1/posts/{id}/schedule | schedules:write | external | Required |
schedules.cancel | POST | /api/v1/schedules/{id}/cancel | schedules:write | external | None |
* Required for new integrations. Earlier REST callers can still use the unkeyed request.
OpenAPI JSONPublishing results
| Result | Client action |
|---|---|
succeeded | The platform confirmed the post. Use the external ID or URL when available. |
pending | Freepost accepted the delivery. Poll its ID or wait for a webhook. |
failed | Read code and message. Retry only if retryable is true, and wait retryAfter seconds when present. |
unknown | Check the destination account and reconcile the delivery in Freepost. Do not resend an unknown delivery. |
Pacing and rate limits
Per-account publishing pace has a configured minimum interval and daily cap. Check platforms.rules for the values and accounts.list for postsLeftToday and nextAllowedPublishAt. Optional credential caps apply across its accounts. Daily caps reset at midnight UTC.
Default request limits per minute are 120 reads, 30 writes, 5 publish-class calls, and 10 expensive calls. REST and stdio share workspace buckets. Remote MCP buckets use the verified credential. A throttled REST request can include Retry-After and X-RateLimit-* headers.
Every plan includes agent access. Reads and validation do not consume plan allowances. Draft creation shares the workspace’s daily post pool. The Free plan has a monthly allowance of 20 external publishes, reset at midnight UTC on the first day of the month. A dispatch counts even if its result is unknown. Paid plans have no monthly external publish cap.
Call GET /api/v1/usage or MCP usage_get for the workspace's current month usage, enforcement status, reset time, and daily post creations remaining.
Webhooks
Subscribe in Settings → Webhooks or use /api/v1/webhooks with webhooks:manage. Freepost retries unsuccessful deliveries. Verify the signature against the original request bytes before parsing JSON.
Subscribable events
publication.succeededpublication.failedpublication.unknownpublication.resolvedschedule.dispatchedaccount.needs_reauth
Node.js signature verification
import { createHmac, timingSafeEqual } from "node:crypto";
export async function verifyFreepostWebhook(request, secret) {
const body = Buffer.from(await request.arrayBuffer());
const signature = request.headers.get("Freepost-Signature") ?? "";
const match = /^t=(0|[1-9][0-9]{0,15}),v1=([a-f0-9]{64})$/.exec(signature);
if (!secret || !match || match[0] !== signature) return null;
const sentAt = Number(match[1]);
const now = Math.floor(Date.now() / 1000);
if (!Number.isSafeInteger(sentAt) || Math.abs(now - sentAt) > 300) return null;
const expected = createHmac("sha256", secret)
.update(match[1] + ".")
.update(body)
.digest();
if (!timingSafeEqual(expected, Buffer.from(match[2], "hex"))) return null;
return JSON.parse(body.toString("utf8"));
}Return 401 for an invalid signature. Use a durable store to process each event ID once, then respond with HTTP 2xx. Freepost-Delivery identifies the webhook delivery and Freepost-Event identifies the event type. Manual redelivery retains the event ID.
Errors
REST errors return error.code and error.message, with optional error.details. A publish result can also report a delivery failure in data.
| HTTP status | Meaning and next action |
|---|---|
400 | Correct invalid request parameters or a missing required idempotency key. |
401 | Supply a valid API key or reconnect the remote MCP client. |
402 | EXTERNAL_PUBLISH_LIMIT_REACHED. Upgrade the workspace or wait for the next UTC month. |
403 | Check the required scope, workspace role, and plan limits. |
404 | The resource is unavailable to this credential. Verify the ID and workspace or account access. |
409 | The key has a different request or the resource state conflicts with this action. |
410 | The resource or legacy RPC endpoint is gone. For publishing, follow the current delivery if one exists. |
422 | Correct the request. Draft validation can include error.details.problems. |
429 | Back off for Retry-After or the indicated pacing interval. |
503 | The service is temporarily unavailable. For a keyed operation, retry with the original key and request. |
Changelog
REST v1, remote MCP, stdio MCP, the agent skill, signed webhooks, and external publishing usage.
POST /api/v1/mcp/{tool} was deprecated on November 20, 2026 and returns 410 from January 19, 2027 at 00:00 UTC. Use the remote MCP server, the registry tools in stdio MCP, or REST v1. Read Deprecation, Sunset, and Link on legacy responses.
Stdio MCP setup