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.

ScopeAccess
posts:readRead workspace posts and publications.
posts:writeValidate, create, update, and delete drafts.
publish:writePublish a draft now.
accounts:readList authorized accounts, inspect platform rules, and read workspace usage.
media:readList media and read media files.
media:writeUpload or import media.
schedules:writeSchedule a draft and cancel a queued schedule.
webhooks:manageManage webhooks and inspect their delivery logs with a workspace-wide key.
analytics:readRead 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.

  1. 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"
  2. 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"'"]}'
  3. 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"
  4. 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/mcp

Local 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 build

Claude 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

OperationMethodPathScopeRisk tierIdempotency key
accounts.listGET/api/v1/accountsaccounts:readreadNone
usage.getGET/api/v1/usageaccounts:readreadNone
platforms.rulesGET/api/v1/platforms/rulesaccounts:readreadNone
posts.getGET/api/v1/posts/{id}posts:readreadNone
publications.getGET/api/v1/publications/{id}posts:readreadNone
media.uploadPOST/api/v1/mediamedia:writedraftNone
posts.validatePOST/api/v1/posts/validateposts:writedraftNone
posts.createPOST/api/v1/postsposts:writedraftRequired*
posts.updatePATCH/api/v1/posts/{id}posts:writedraftNone
posts.deleteDELETE/api/v1/posts/{id}posts:writedraftNone
posts.publishPOST/api/v1/posts/{id}/publishpublish:writeexternalRequired*
posts.schedulePOST/api/v1/posts/{id}/scheduleschedules:writeexternalRequired
schedules.cancelPOST/api/v1/schedules/{id}/cancelschedules:writeexternalNone

* Required for new integrations. Earlier REST callers can still use the unkeyed request.

OpenAPI JSON

Publishing results

ResultClient action
succeededThe platform confirmed the post. Use the external ID or URL when available.
pendingFreepost accepted the delivery. Poll its ID or wait for a webhook.
failedRead code and message. Retry only if retryable is true, and wait retryAfter seconds when present.
unknownCheck 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.succeeded
  • publication.failed
  • publication.unknown
  • publication.resolved
  • schedule.dispatched
  • account.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 statusMeaning and next action
400Correct invalid request parameters or a missing required idempotency key.
401Supply a valid API key or reconnect the remote MCP client.
402EXTERNAL_PUBLISH_LIMIT_REACHED. Upgrade the workspace or wait for the next UTC month.
403Check the required scope, workspace role, and plan limits.
404The resource is unavailable to this credential. Verify the ID and workspace or account access.
409The key has a different request or the resource state conflicts with this action.
410The resource or legacy RPC endpoint is gone. For publishing, follow the current delivery if one exists.
422Correct the request. Draft validation can include error.details.problems.
429Back off for Retry-After or the indicated pacing interval.
503The 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