> ## Documentation Index
> Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastodon Posting API Documentation | Kavenio Docs

> Connect Mastodon accounts across instances and publish statuses, media, polls, and content warnings. Review OAuth, server limits, payloads, and errors.

Kavenio publishes to Mastodon through accounts connected on their own Mastodon
instances. Use `mastodon` as the platform value in post payloads.

For a product-level overview, see the
[Mastodon posting API](https://kavenio.com/platforms/mastodon) page.

## Connect

Start Mastodon OAuth with the account's instance domain:

```bash theme={null}
kavenio connect begin \
  --profile-id customer_user_123 \
  --platform mastodon \
  --mastodon-instance mastodon.social \
  --return-to https://app.example.com/accounts
```

For direct API use, send `mastodonInstance` in `POST /v1/connect/begin`.
Kavenio owns the provider `redirect_uri` and uses `/v1/connect/callback` to
exchange the authorization code and store encrypted account credentials.
Use `returnTo` for the browser destination after Kavenio completes the
connection.

Kavenio registers a reusable OAuth app per Mastodon instance, callback URL, and
scope set. After the first registration, repeat connects for the same instance
reuse the cached app registration instead of calling the instance app
registration endpoint again. If an instance rate-limits app registration before
the cache exists, the API returns a provider rate-limit error with retry timing
when the instance supplies it.

## Publishing

Kavenio supports Mastodon text posts, images, GIFs, videos, audio, replies,
quote references on compatible instances, content warnings, sensitive-media
flags, language, visibility, and polls.

Use Kavenio `scheduledFor` for scheduled publishing. Provider-native
`scheduledAt` is not accepted because Kavenio's durable publish worker remains
the authoritative schedule and status source.

Quote posts require Mastodon 4.5 or API version 7 support and cannot be combined
with media or polls. Kavenio checks the connected instance before publishing a
quote. `localOnly` is not exposed as generic Mastodon functionality because it
is a server-fork extension rather than part of the standard Mastodon statuses
API.

## Engagement

Connected Mastodon accounts can list notifications, dismiss notifications, list
persisted notification, conversation, and status-reply engagement items synced
by background jobs, list direct conversations, mark conversations read, fetch
status context, read and reply to published-status comments through the generic
post comments API, and run status actions such as favourite, unfavourite, boost,
unboost, bookmark, unbookmark, mute, and unmute.

The shared engagement inbox at `GET /v1/inbox/engagement` lists persisted
Mastodon notifications and status replies across connected Mastodon accounts.
Direct conversations are excluded unless `includeDirect=true` is supplied.

## Limits

* Text, URL, media, MIME, byte, dimension, frame-rate, alt-description, and poll
  limits are read from the connected instance. Kavenio uses conservative
  Mastodon defaults when an instance does not return a value.
* Polls cannot be combined with media.
* Engagement APIs require the matching Mastodon OAuth scopes. Reconnect the
  account if an older connection is missing a required scope.

## Unsupported

Kavenio does not support Mastodon ads, provider-native scheduling, generic
local-only posts, or streaming sync yet. Published status edit and
delete/unpublish are supported. The shared engagement inbox currently supports
persisted Mastodon items; additional non-Mastodon engagement providers can be
added behind the same endpoint later.

## Official Mastodon API References

* [API guidelines for multi-server login](https://docs.joinmastodon.org/api/guidelines/)
* [OAuth authorization methods](https://docs.joinmastodon.org/methods/oauth/)
* [Creating statuses, polls, replies, and quotes](https://docs.joinmastodon.org/methods/statuses/)
* [Instance-specific status, media, and poll limits](https://docs.joinmastodon.org/entities/Instance/)
* [Uploading media](https://docs.joinmastodon.org/methods/media/)