API & MCP

    Your workflow, connected to Postoir.

    Create drafts, publish to your social accounts and schedule what comes next. Use our API from your scripts or connect a compatible AI assistant to our hosted MCP server.

    Connect an assistantUse the API

    Included with an active Basic, Pro or Enterprise subscription. Compare plans

    Prepare your content

    Read posts, find connected accounts and media, and create or edit drafts. Campaigns are optional.

    Publish from your tools

    Request delivery to selected accounts on X, Instagram, Facebook, LinkedIn, TikTok and Discord.

    Choose the right time

    Schedule with an explicit timezone, move a scheduled post, or cancel before delivery starts.

    Start with an organization key

    1. Connect your social accounts in Postoir and select the organization you want to use.
    2. Open Organization → API keys. Only owners and administrators can create keys.
    3. Choose Read only to inspect content, or Full access to create, edit, delete, publish and schedule posts.
    4. Save the key when it is shown. Paste it into your application's credential configuration, never into a chat or a public repository.

    Each key accesses one organization. Starter and Pay As You Go do not include API or MCP access. Revoked or expired keys stop working, and access pauses when the subscription is inactive.

    Connect with MCP

    Postoir hosts the server for you. Add this URL to a client that supports Streamable HTTP and an Authorization header. No Postoir source code, local server or compilation is needed.

    MCP server URL
    https://postoir.com/mcp

    Cursor

    Add this to your personal MCP configuration. Replace the placeholder with your organization key and keep the file private.

    Cursor MCP configuration
    {
  "mcpServers": {
    "postoir": {
      "url": "https://postoir.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_POSTOIR_API_KEY"
      }
    }
  }
}

    Claude Code

    Set POSTOIR_API_KEY in your local environment, then register the hosted server. Your local client configuration contains the credential.

    Claude Code setup
    claude mcp add --transport http postoir https://postoir.com/mcp \
  --header "Authorization: Bearer $POSTOIR_API_KEY"

    Check your assistant's authentication support

    Claude offers request-header authentication in beta for organization administrators: add the server URL, then an Authorization header with the value Bearer followed by your key. Availability depends on your Claude workspace. ChatGPT does not support custom API keys for MCP, so this version cannot connect directly to ChatGPT.

    Claude authentication guide or ChatGPT authentication guide

    Try your first request

    “Use Postoir to list my connected social accounts, then create a draft for the account I choose. Do not publish it yet.”

    When ready, explicitly ask your assistant to publish or schedule the draft. It can use get_post to check the result and retrieve the published links.

    Build with the API

    Set POSTOIR_API_KEY in your environment. Use IDs from the list endpoints below; media must already be uploaded in Postoir.

    Find accounts and media
    curl -H "Authorization: Bearer $POSTOIR_API_KEY" https://postoir.com/api/v1/social-accounts
curl -H "Authorization: Bearer $POSTOIR_API_KEY" https://postoir.com/api/v1/media
    Create a draft
    curl -X POST https://postoir.com/api/v1/posts \
  -H "Authorization: Bearer $POSTOIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-001" \
  -d '{"content":"Our next chapter starts today.","socialAccountIds":["REPLACE_WITH_ACCOUNT_UUID"]}'

    Save data.id from the response as POST_ID. Reuse the same Idempotency-Key only when retrying that exact creation. A different body with the same key returns 409.

    Publish now
    curl -X POST -H "Authorization: Bearer $POSTOIR_API_KEY" https://postoir.com/api/v1/posts/$POST_ID/publish

    A 202 response means delivery was accepted. It does not mean all networks have published the post. Poll the post to inspect each publication's status and externalUrl.

    Schedule instead of publishing now
    curl -X POST https://postoir.com/api/v1/posts/$POST_ID/schedule \
  -H "Authorization: Bearer $POSTOIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledFor":"2030-01-15T09:00:00+01:00"}'

    Replace the example with your chosen future date and timezone. Repeat the schedule request to move a post before delivery starts. Publication consumes the same post quota or credits as the dashboard; cancelling does not refund that consumption.

    Follow delivery or cancel a schedule
    curl -H "Authorization: Bearer $POSTOIR_API_KEY" https://postoir.com/api/v1/posts/$POST_ID

# Cancel only if delivery has not started
curl -X DELETE -H "Authorization: Bearer $POSTOIR_API_KEY" https://postoir.com/api/v1/posts/$POST_ID/schedule

    Troubleshooting

    401 = Check the key
    Use the Authorization header with Bearer and a valid key. Check expiry and revocation in the dashboard.
    403 = Check access
    Check the organization subscription, key permissions and available post quota or credits.
    409 = Check the post
    Delivery may have started, the post may be immutable, or an idempotency key may have been reused with different content. Read the error code and current post.
    429 / 503 = Retry later
    Respect Retry-After. After a publication queue error, read the post first: the saved request may already be processing.

    API responses use data and optional pagination. Errors include code, message and requestId. Limits are 120 requests per minute per key and 600 per organization; MCP protocol requests and their API calls both count. Keep X-Request-Id when contacting support. Some provider failures need a dashboard review before retrying.