Mastodon API for AI agents

Updated October 2026

How do you post to Mastodon from an AI agent?

Connect your Mastodon account to Chirpie once with OAuth on your own server, then let the agent call POST /api/v1/posts or the chirpie_post MCP tool. Chirpie works with any Mastodon server, registers itself there automatically, uploads images and video, publishes native threads, and brings replies back through the comments API.

What Chirpie does on Mastodon

• Posts of up to 500 characters on any Mastodon-compatible server, published now or at a scheduled time.
• Threads of 2 to 25 posts as a native reply chain, all or nothing: if a part fails, every part already published is deleted. See Threads.
• Media: up to 4 images (JPEG, PNG, WebP or GIF, 8 MB each) or 1 video (MP4 or MOV, up to 40 MB), with alt text up to 1,500 characters. See Media.
• Comments: list the replies to a post Chirpie published, answer them, and delete your own replies. See Comments.
• Analytics: favourites, boosts and replies. See Analytics.
• Scheduling, drafts and editing: queue a post, save a draft, or edit a post until it goes out. See Scheduling.
• Several accounts at once: one request publishes to Mastodon and your other networks. See Post to several accounts at once.
• Delete: removes the post from your server and keeps Chirpie's record of it, marked deleted.

Connect your Mastodon account

Mastodon connects with OAuth on your own server. Add Mastodon on the Accounts page and enter your server, or start the flow from the API and open the authorization_url it returns:

curl -X POST https://chirpie.ai/api/v1/accounts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "mastodon", "instance_url": "mastodon.social" }'

The server can be given as mastodon.social, your handle (@you@mastodon.social) or your profile URL. From the terminal, chirpie accounts connect-mastodon --instance mastodon.social. From an agent, the chirpie_connect_mastodon tool takes the same value.

Post from code

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_MASTODON_ACCOUNT_ID",
    "posts": [
      { "text": "We open-sourced our agent test harness today. A short thread." },
      { "text": "It runs the whole customer journey with no human and no real network." }
    ]
  }'

import { ChirpieClient } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

await chirpie.createPost({
  account_id: "YOUR_MASTODON_ACCOUNT_ID",
  text: "Release 2.4 is out. Changelog: https://example.com/changelog",
});

The full request reference is Posts and Threads.

Post from Claude or ChatGPT

Add Chirpie to Claude from its listing in the Claude Connectors Directory, or add https://chirpie.ai/mcp as an app in ChatGPT developer mode, and sign in. Then ask:

• "Post this release note to Mastodon and Bluesky."
• "Thread our changelog on Mastodon, one change per post."
• "Which replies to my last Mastodon post are questions? Draft answers."

Setup guides: Claude, ChatGPT. A walkthrough from Claude Code is in Post to Bluesky and Mastodon from Claude Code.

Frequently asked questions

Which Mastodon servers does Chirpie work with?

Any server running Mastodon or a Mastodon-compatible fork such as Hometown or Glitch-soc, over HTTPS. Chirpie registers itself on your server the first time you connect, so there is nothing to set up there.

How long can a Mastodon post be through Chirpie?

500 characters, Mastodon's standard limit. Chirpie applies 500 to every server, so a post that passes on one server passes on all of them.

Can an AI agent post video to Mastodon?

Yes. A Mastodon post takes up to 4 images (JPEG, PNG, WebP or GIF, up to 8 MB each) or 1 video (MP4 or MOV, up to 40 MB), with alt text up to 1,500 characters.

Do Mastodon tokens expire?

No. A Mastodon token lasts until you revoke it. If you revoke it on your server, reconnect the account from the Chirpie dashboard.

Which Mastodon metrics does Chirpie report?

Favourites, boosts and replies for each published post. Mastodon publishes no impression counts, so none are reported.