Information
- License: MIT
- OpenAPI version:
3.1.0
The client API of my, an ActivityPub microblog server. It is not compatible with the Mastodon client API.
application/problem+json) whose title
and detail are localized from Accept-Language. Clients branch on type and status,
never on the text.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.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.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).GET /openapi.yaml, without a limit or a token.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.
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:
For LLMs and coding agents:llms.txt,llms-full.txt, llms-small.txt