Skip to content

Overview

The client API of my, an ActivityPub microblog server. It is not compatible with the Mastodon client API.

  • Every error is an RFC 9457 problem document (application/problem+json) whose title and detail are localized from Accept-Language. Clients branch on type and status, never on the text.
  • Requests authenticate with an OAuth 2.0 access token in Authorization: Bearer, never with cookies. Each operation lists the scopes it needs under security; a broad scope (read, write, follow, admin) grants the fine-grained scopes under it. A missing or invalid token is a 401 with WWW-Authenticate, a token without the scope a 403 insufficient_scope.
  • The operations carry the RateLimit and RateLimit-Policy fields (draft-ietf-httpapi-ratelimit-headers): anonymous requests share a limit per client IP, authenticated requests one per account, and an administrator may cap one client across all its users (the client policy). Past a limit the answer is 429 with Retry-After. The fields are left out while the server cannot read its limits, which then let requests through.
  • Every write (POST, PUT, PATCH, DELETE) takes an Idempotency-Key, with which a request whose answer did not arrive is sent again and carried out once. The few whose answer carries a secret take none (x-no-idempotency-key says why).
  • This document is served at GET /openapi.yaml, without a limit or a token.
  • IDs are UUIDv7 strings. Collections use keyset pagination: pass the next_cursor of a page as cursor to get the next page.

Each object schema of the requests and responses has a page of its own, listed under Schemas.

Information

  • License: MIT
  • OpenAPI version: 3.1.0

An OAuth 2.0 access token (Authorization Code + PKCE S256), sent as Authorization: Bearer <token>. read, write, follow, and admin grant every scope under them (read grants read:accounts; follow grants read:follows, read:blocks, read:mutes, write:follows, write:blocks, and write:mutes; admin grants admin:read and admin:write). read and write do not grant the admin scopes.

read:statuses does not show posts whose visibility is direct, in timelines, in a post’s thread, or in a post’s own response, nor in the posts of a notification; read:direct (which read grants) does. The same holds for bookmarks, favourites, a post’s source, and the posts that quote a post, the user’s own direct posts included. Sending a direct post needs only write:statuses, and the response shows the post just sent.

A write scope reads the post it acts on: the response to an action on a post, such as favouriting it with write:favourites, is the whole post. A token without read:direct cannot act on a direct post, the user’s own included (editing or deleting it, or setting who may quote it, say): it gets a 404 and nothing changes. It can still take back what the user had on one (a favourite, say), and the answer is the same 404, which shows nothing of the post.

Only the server’s own (first-party) clients may hold admin, admin:read, admin:write, and write:supporters: an authorization request of any other client that asks for one is refused with invalid_scope, and a broad scope such as write does not give such a client write:supporters. The operations that change how the user signs in or ends the account (password, two-factor authentication, passkeys, linked identities, signed-in browsers, authorized apps, moving, deactivating, and deleting the account, the user’s own OAuth apps), and those whose consequences a consent screen cannot explain (data exports and imports, changing and previewing the automatic deletion of posts, adding and removing aliases, invites, the user’s moderation actions and appeals), are marked x-first-party-only: true; whatever its scopes, the token of another client gets a 403 /api/v1/problems/first-party-only from them.

A permission scope admin:<permission> (admin:manage_invites, admin:manage_finance, …) stands in for admin:read and admin:write on the admin operations that need that permission of the user’s roles, which each names with x-permission; every call still needs the permission on the user’s roles. Only a token that the user issues to themselves from an OAuth app they registered (issueOAuthAppToken) may hold one, and only for a permission their roles hold when it is issued: an authorization request of any client but the server’s own asks for one in vain (invalid_scope). Such a token reaches only the permissions its scopes name: an operation without x-permission, or one that needs another permission, answers 403 /api/v1/problems/insufficient-scope, and a webhook it sets up subscribes only to events that its permissions show. manage_roles, manage_oauth_apps, manage_login_recovery, manage_login_providers, manage_service_closure, and the member permissions have no permission scope. admin grants every permission scope.

The moderator notifications (admin_report, admin_appeal, admin_sign_up, admin_error_group, and the other types that need a role’s permission) reach first-party clients only: another client’s token, whatever the user’s roles, does not get them in the notification list, the stream, or the unread count, and they are dropped from the alerts of its Web Push subscription.

read:notifications shows a notification’s status, under the rule of read:direct above, and its type tells what happened. The other objects that a notification carries need the scope that reads them elsewhere, and are omitted without it: report needs read:reports, supporter_subscription read:supporters, custom_emoji_request read:custom_emojis, relationship_severance read:follows, voice_room read:voice, and event read:events. moderation_action reaches first-party clients only.

Security scheme type: oauth2

Flow type: authorizationCode

Authorization URL: /oauth/authorize

Token URL: /oauth/token

Refresh URL: /oauth/token

Scopes:

  • admin - Administer the instance, as far as the user's roles allow (first-party clients only).
  • admin:read - Read the instance's administration data, as far as the user's roles allow (first-party clients only).
  • admin:write - Change the instance's administration data, as far as the user's roles allow (first-party clients only).
  • admin:manage_reports - Use the permission manage_reports of the user's roles (tokens the user issues to themselves only).
  • admin:manage_accounts - Use the permission manage_accounts of the user's roles (tokens the user issues to themselves only).
  • admin:manage_domains - Use the permission manage_domains of the user's roles (tokens the user issues to themselves only).
  • admin:manage_rules - Use the permission manage_rules of the user's roles (tokens the user issues to themselves only).
  • admin:manage_settings - Use the permission manage_settings of the user's roles (tokens the user issues to themselves only).
  • admin:manage_invites - Use the permission manage_invites of the user's roles (tokens the user issues to themselves only).
  • admin:view_audit - Use the permission view_audit of the user's roles (tokens the user issues to themselves only).
  • admin:manage_jobs - Use the permission manage_jobs of the user's roles (tokens the user issues to themselves only).
  • admin:manage_custom_emojis - Use the permission manage_custom_emojis of the user's roles (tokens the user issues to themselves only).
  • admin:manage_webhooks - Use the permission manage_webhooks of the user's roles (tokens the user issues to themselves only).
  • admin:manage_announcements - Use the permission manage_announcements of the user's roles (tokens the user issues to themselves only).
  • admin:manage_finance - Use the permission manage_finance of the user's roles (tokens the user issues to themselves only).
  • admin:manage_supporters - Use the permission manage_supporters of the user's roles (tokens the user issues to themselves only).
  • admin:manage_errors - Use the permission manage_errors of the user's roles (tokens the user issues to themselves only).
  • read - Read everything the user can read.
  • write - Change everything the user can change.
  • follow - Read and change follows, blocks, and mutes.
  • push - Receive Web Push notifications.
  • read:accounts - Read accounts and their followers and follows, and the user's own account with its roles and permissions, preferences (including whether emails still reach the address), notification settings and policy, aliases, and automatic deletion policy.
  • read:blocks - Read the accounts the user blocks.
  • read:bookmarks - Read the user's bookmarks.
  • read:custom_emojis - Read the custom emoji the user made and their requests for new ones.
  • read:direct - Read the direct posts the user sends and receives and their conversations (`read:statuses` does not show them).
  • read:events - Read the events the user sees, their attendees, and the invitations of the events the user organizes.
  • read:favourites - Read the posts the user favourited.
  • read:filters - Read the user's keyword filters.
  • read:finance - Read the totals of the instance's costs and income, as far as the user's roles allow.
  • read:follows - Read follows, follow requests, lists, followed hashtags, and the accounts whose new posts notify the user.
  • read:mutes - Read the accounts and domains the user mutes.
  • read:notifications - Read the user's notifications and the notification requests.
  • read:reports - Read the reports the user filed and whether they are resolved.
  • read:statuses - Read posts and timelines.
  • read:supporters - Read the user's own supporter subscription.
  • read:voice - Read the voice chat rooms the user sees.
  • write:accounts - Change the user's profile, featured hashtags, preferences, notification settings and policy, badges, and supporter listing.
  • write:blocks - Block and unblock accounts.
  • write:bookmarks - Bookmark posts and remove bookmarks.
  • write:custom_emojis - Request new custom emoji, and change and delete the ones the user made.
  • write:events - Create, change, and cancel events, answer them, approve their attendees, invite to them, and name their co-organizers.
  • write:favourites - Favourite posts and react to them with emoji, and take both back.
  • write:filters - Create, change, and delete the user's keyword filters.
  • write:follows - Follow and unfollow accounts and hashtags, answer follow requests, change lists, and subscribe to the new posts of accounts.
  • write:media - Upload media, read their state while they process, and change their descriptions.
  • write:mutes - Mute and unmute accounts, domains, and threads.
  • write:notifications - Mark notifications read and dismiss them, and accept and dismiss the notification requests.
  • write:reports - Report accounts and posts to the moderators.
  • write:statuses - Post, edit, delete, boost, and pin posts, vote in polls, and set who may quote a post.
  • write:supporters - Subscribe to the supporter plans, and change, cancel, and resume the subscription (first-party clients only).
  • write:voice - Open, join, and leave voice chat rooms, and host them.

For LLMs and coding agents:llms.txt,llms-full.txt, llms-small.txt

Analytics on this site