canonical: https://jentic.com/apis/joinmastodon.org/mastodon # Joinmastodon Mastodon API Mastodon is a federated, open-source social network where each instance hosts its own users while interoperating across the wider fediverse. This subset of the Mastodon API focuses on the statuses surface - posting, editing, deleting, boosting, favouriting, bookmarking, pinning, and translating posts, plus retrieving conversation context and edit history. It is the right toolkit when an agent needs to publish to a Mastodon instance or moderate a thread on behalf of a user. ## For AI agents Post and edit Mastodon statuses, boost or favourite posts, manage bookmarks and pins, translate content, and walk thread context - all against any Mastodon instance the user authenticates against. ## Scope Does not handle account follow management, direct messages, instance administration, or media upload - use for status-level publishing, interactions, and thread retrieval only. ## Capabilities - Post a new status to a Mastodon instance with visibility and language settings - Edit or delete a previously published status and inspect its edit history - Boost (reblog) and unboost a status to amplify it on the user's timeline - Favourite, bookmark, or pin a status, with matching undo operations - Mute a conversation thread to suppress notifications without leaving it - Retrieve a status's parent and child context to walk a full thread - Translate a status into another language using the instance's translation backend ## Use cases ### Cross-post to Mastodon from a content workflow Marketing or community teams publishing on multiple networks can mirror posts to Mastodon by calling POST /statuses with the rendered text, visibility, and language. The endpoint returns the new status's ID, which can be stored alongside cross-post metadata for later editing or deletion. This works against any Mastodon instance, so brands hosted on their own servers and those on mastodon.social use the same call. Example prompt: Call POST /statuses with status text 'New release shipped today - details on the blog' and visibility 'public' to publish to the user's instance ### Walk a thread and summarise the conversation Researchers and community managers can pull the full context around a status - both ancestors and descendants - using GET /statuses/{id}/context. The response groups parents and children separately, making it straightforward to render a threaded view or feed an LLM a complete conversation for summarisation. Pair this with the source endpoint to inspect the original markdown of the focal post. Example prompt: Call GET /statuses/{id}/context for the focal status, concatenate ancestor and descendant statuses, and feed the joined text to the assistant for summarisation ### Curate a personal bookmark and pin set Power users who treat their Mastodon profile as a curated feed can manage pins and bookmarks programmatically. POST /statuses/{id}/bookmark saves a post for later, POST /statuses/{id}/pin highlights it on the profile, and the matching unpin and unbookmark endpoints reverse the action cleanly. This is useful for daily-digest bots that pin a featured post each morning. Example prompt: Call POST /statuses/{id}/pin to feature the morning announcement, then POST /statuses/{previous_id}/unpin to remove yesterday's pinned status ### Agent-driven Mastodon posting via Jentic An AI assistant can be granted scoped Mastodon access through Jentic so it can publish on behalf of a user without ever holding the access token in memory. The agent expresses intent ('post my weekly update to Mastodon'), Jentic resolves to POST /statuses, injects the bearer token, and returns the new status URL. Multi-instance support is handled through the {instance} server template. Example prompt: Use Jentic to search 'post to Mastodon', load POST /statuses, and execute it with the user's stored bearer token to publish a weekly update ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /statuses | Post a new status | | GET | /statuses/{id} | View a single status | | PUT | /statuses/{id} | Edit a status | | DELETE | /statuses/{id} | Delete a status | | GET | /statuses/{id}/context | Get parent and child statuses | | POST | /statuses/{id}/favourite | Favourite a status | | POST | /statuses/{id}/reblog | Boost a status | | POST | /statuses/{id}/translate | Translate a status | ## Key resources - **Statuses** — Create, view, edit, delete, and translate Mastodon posts - **Interactions** — Favourite, boost, bookmark, pin, and mute operations on statuses - **Thread Context** — Walk parent and child statuses and inspect edit history and source ## Why Jentic - **Setup:** Wiring the Mastodon API by hand means learning its bearer auth, resolving the correct instance host for each account, and handling per-status interactions yourself. Through Jentic you install once, import the Mastodon API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Mastodon puts the status id in the URL path (/statuses/{id}), so a rule can pin your agent to one status: it can fetch context, favourite, or reblog that status and nothing else. You choose the operations it may call, so destructive ones like deleting a status are not included unless you add them. - **Credential handling:** Your Mastodon bearer token, scoped to its instance, is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'post to Mastodon' or 'boost a status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Bluesky API** — AT Protocol-based decentralised microblog with overlapping feature surface - **X (Twitter) API** — Centralised microblog network - broader reach, paid API tiers - **Slack API** — Cross-post Mastodon updates into a Slack channel for internal awareness ## FAQ ### What authentication does the Mastodon API use? The Mastodon API uses HTTP bearer authentication - an Authorization: Bearer {access_token} header obtained via the OAuth flow on the user's instance. Jentic stores tokens encrypted per-user and injects them at call time, keeping them out of the agent's context. ### Can I post a status with the Mastodon API? Yes. POST /statuses creates a new status with parameters for status text, visibility (public, unlisted, private, direct), and language. The response returns the new status's ID, URL, and account details, which you can use for subsequent edits or deletes. ### How do I work with multiple Mastodon instances? The base URL uses an {instance} template - every Mastodon server (mastodon.social, hachyderm.io, your self-hosted instance) implements the same endpoints. Configure the instance hostname per credential and the same operations apply across the fediverse. ### How do I post to Mastodon through Jentic? Search Jentic for 'post to Mastodon', load POST /statuses, and execute it with the user's instance bearer token. Jentic returns the created status, including its URL. Get started with Jentic One, the self-hosted execution layer. ### Can the Mastodon API translate a post into another language? Yes. POST /statuses/{id}/translate asks the instance's configured translation backend to translate a status. Availability depends on the instance - admins can enable or disable the feature, so check the response status before relying on it. ### How do I retrieve the full context of a Mastodon thread? Call GET /statuses/{id}/context for the focal status. The response contains an 'ancestors' array (parents) and 'descendants' array (replies), letting you reconstruct the full conversation in a single call. ### Can I limit what my agent is allowed to do with the Mastodon API? Yes. Because you run Jentic One yourself, you decide which Mastodon operations your agent may call, so read-only actions like fetching a thread with GET /statuses/{id}/context or favouriting and boosting a post can be allowed while destructive ones like DELETE /statuses/{id} are left out. Since the status id sits in the URL path, a rule can even pin the agent to a single status, letting it fetch context or reblog that one post and nothing else. The bearer token stays with your own instance and is injected at call time, so the agent only ever exercises the operations your rules permit.