Mastodon API: How to Post to Mastodon via API

The official Mastodon API

Posts (statuses) are created with POST /api/v1/statuses on the account's own server, using a user token with the write:statuses scope. The request takes status text, media_ids[] for attachments uploaded beforehand, visibility (public, unlisted, private or direct), spoiler_text for a content warning, and an optional scheduled_at at least 5 minutes in the future. An Idempotency-Key header prevents duplicate posts on retries.

What posting requires

1. Register an application on the target instance with POST /api/v1/apps (client_name, redirect_uris, scopes). Apps are registered per instance.
2. Send the user through the OAuth authorization flow on that instance and exchange the code at /oauth/token for an access token.
3. Store the client secret and access token like passwords.
4. Upload media first with the media endpoint, then pass the returned IDs in media_ids[] when you create the status.
5. Repeat app registration for every additional server your users are on.

Cost: Free. The Mastodon API has no fee or review process; each server applies its own rate limits.

Official limits

Common gotchas

• There is no single Mastodon API host. Every user's server is a separate API with its own app registration and tokens.
• Character limits and media limits vary by instance, so a post that fits on one server can be rejected on another.
• Media uploads are limited to 30 per 30 minutes, which a bulk import can hit quickly.
• Deleting and re-posting to fix a mistake counts against the 30 deletes per 30 minutes limit.
• Retries without an Idempotency-Key can create duplicate toots.

Post to Mastodon via API

curl -X POST https://api.publora.com/api/v1/create-post \
  -H "Content-Type: application/json" \
  -H "x-publora-key: sk_YOUR_API_KEY" \
  -d '{
    "content": "Version 2.4 is out: faster search, CSV export and a dark mode that follows your system setting. #OpenSource #ReleaseNotes",
    "platforms": ["mastodon-109876543210"],
    "scheduledTime": "2026-10-08T15:30:00.000Z"
  }'
# { "success": true, "postGroupId": "...", "scheduledTime": "2026-10-08T15:30:00.000Z" }

import uuid
import requests

response = requests.post(
    "https://api.publora.com/api/v1/create-post",
    headers={
        "Content-Type": "application/json",
        "x-publora-key": "sk_YOUR_API_KEY",
        # Reuse the same key if you retry this exact request.
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "content": "Version 2.4 is out: faster search and CSV export. #OpenSource",
        "platforms": ["mastodon-109876543210", "bluesky-did:plc:abc123xyz"],
        "scheduledTime": "2026-10-08T15:30:00.000Z",
    },
)
print(response.json())  # {'success': True, 'postGroupId': '...', 'scheduledTime': '...'}

Or let an AI agent post

Connect any MCP client to mcp.publora.com:

• “Write a Mastodon post under 480 characters announcing our 2.4 release with CamelCase hashtags, and schedule it for Wednesday at 15:30 UTC.”
• “Check post stats for my Mastodon toots from the last two weeks and list the three with the most boosts.”
• “Post the same release note to my Mastodon and Bluesky accounts tomorrow at 09:00 UTC, trimmed to fit Bluesky's 300 characters.”