OpenAPI Specification
openapi: 3.0.0
servers:
- description: 'Any instance server.'
url: '{{baseUrl}}'
info:
title: Mastodon API
description: This is an OpenAPI for the Mastodon API.
version: 1.0.0
contact:
name: Kin Lane
email: [email protected]
tags:
- name: Social
description: The acitivity via social media.
paths:
/health:
get:
summary: ""
operationId: ""
description: Returns ok to indicate server is up
responses:
"200":
description: search results matching criteria
content:
text/plain:
schema:
type: string
"400":
description: bad input parameter
/oauth/authorize/native:
get:
responses:
"200":
description: "native_oauth_authorization Controller#Action
oauth/authorizations#show"
tags:
- oauth
- todo
/oauth/authorize:
description: Displays an authorization form to the user. If approved, it will
create and return an authorization code, then redirect to the desired
redirect_uri, or show the authorization code if urn:ietf:wg:oauth:2.0:oob
was requested. The authorization code can be used while requesting a token
to obtain access to user-level methods.
get:
parameters:
- in: query
name: response_type
required: true
schema:
type: string
enum:
- code
description: Should be set equal to code.
- in: query
name: client_id
required: true
schema:
type: string
description: Client ID, obtained during app registration.
- in: query
name: redirect_uri
required: true
schema:
type: string
description: Set a URI to redirect the user to. If this parameter is set to
urn:ietf:wg:oauth:2.0:oob then the authorization code will be shown
instead. Must match one of the redirect URIs declared during app
registration.
- in: query
name: scope
schema:
type: string
description: List of requested OAuth scopes, separated by spaces (or by pluses,
if using query parameters). Must be a subset of scopes declared
during app registration. If not provided, defaults to read.
- in: query
name: force_login
schema:
type: boolean
description: Added in 2.6.0. Forces the user to re-login, which is necessary for
authorizing with multiple accounts from the same instance.
responses:
"200":
description: "oauth_authorization Controller#Action
oauth/authorizations#new"
tags:
- oauth
- todo
delete:
responses:
"200":
description: "Controller#Action oauth/authorizations#destroy"
tags:
- oauth
- todo
post:
responses:
"200":
description: "Controller#Action oauth/authorizations#create"
tags:
- oauth
- todo
/oauth/token:
post:
description: Obtain an oauth token for API requests.
requestBody:
content:
application/form-data:
schema:
type: object
required:
- grant_type
- client_id
- client_secret
- redirect_uri
properties:
grant_type:
type: string
description: Set equal to authorization_code if code is provided in order to
gain user-level access. Otherwise, set equal to
client_credentials to obtain app-level access only.
client_id:
type: string
description: Client ID, obtained during app registration
client_secret:
type: string
description: Client secret, obtained during app registration
redirect_uri:
type: string
description: Set a URI to redirect the user to. If this parameter is set to
urn:ietf:wg:oauth:2.0:oob then the token will be shown
instead. Must match one of the redirect URIs declared during
app registration.
scope:
type: string
description: List of requested OAuth scopes, separated by spaces. Must be a
subset of scopes declared during app registration. If not
provided, defaults to read.
code:
type: string
description: A user authorization code, obtained via /oauth/authorize
examples:
app token:
value:
client_id: 3N5yVaa_d8TJozehuHAHGXrgAWQstWb1W03efWoDNsM
client_secret: Hl6FKbQZ2BE4T2i-MqKVRvEqqzzidsy-h9K3612VFyY
redirect_uri: urn:ietf:wg:oauth:2.0:oob
grant_type: client_credentials
user token:
value:
client_id: QfxXkqC6WLbhs4HyjH3oM1nMetdLot0mSK2Bp9KoZbk
client_secret: 3q-V6Gc85VzQIlXKgsT21IYHgSC2KKxap4tvTkj_24w
redirect_uri: urn:ietf:wg:oauth:2.0:oob
grant_type: authorization_code
code: NiYRkKURwiU6zMMoRFkcTXPwSr_jLWhMDvY-bZCzxJM
scope: read write follow push
responses:
"200":
description: "oauth_token Controller#Action oauth/tokens#create"
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
token_type:
type: string
scope:
type: string
created_at:
type: integer
example:
access_token: {{token}}
token_type: Bearer
scope: read
created_at: 1635107910
tags:
- oauth
/oauth/revoke:
post:
responses:
"200":
description: "oauth_revoke Controller#Action oauth/tokens#revoke"
tags:
- oauth
- todo
/oauth/introspect:
post:
responses:
"200":
description: "oauth_introspect Controller#Action oauth/tokens#introspect"
tags:
- oauth
- todo
/oauth/applications:
get:
responses:
"200":
description: "oauth_applications Controller#Action
doorkeeper/applications#index"
tags:
- oauth
- todo
post:
responses:
"200":
description: "Controller#Action doorkeeper/applications#create"
tags:
- oauth
- todo
/oauth/applications/new:
get:
responses:
"200":
description: "new_oauth_application Controller#Action
doorkeeper/applications#new"
tags:
- oauth
- todo
"/oauth/applications/{id}/edit":
parameters:
- in: path
name: id
required: true
schema:
type: integer
get:
responses:
"200":
description: "edit_oauth_application Controller#Action
doorkeeper/applications#edit"
tags:
- oauth
- todo
"/oauth/applications/{id}":
parameters:
- in: path
name: id
required: true
schema:
type: integer
get:
responses:
"200":
description: "oauth_application Controller#Action
doorkeeper/applications#show"
tags:
- oauth
- todo
patch:
responses:
"200":
description: " Controller#Action doorkeeper/applications#update"
tags:
- oauth
- todo
put:
responses:
"200":
description: "Controller#Action doorkeeper/applications#update"
tags:
- oauth
- todo
delete:
responses:
"200":
description: "Controller#Action doorkeeper/applications#destroy"
tags:
- oauth
- todo
/oauth/authorized_applications:
get:
responses:
"200":
description: "oauth_authorized_applications Controller#Action
oauth/authorized_applications#index"
tags:
- oauth
- todo
"/oauth/authorized_applications/{id}":
parameters:
- in: path
name: id
required: true
schema:
type: integer
delete:
responses:
"200":
description: "oauth_authorized_application Controller#Action
oauth/authorized_applications#destroy"
tags:
- oauth
- todo
/.well-known/host-meta:
get:
tags:
- well-known
responses:
"200":
description: Prefix host_meta Controller#Action well_known/host_meta#show
{:format=>"xml"}
content:
application/xrd+xml:
example: <?xml version=\"1.0\" encoding=\"UTF-8\"?> <XRD
xmlns=\"http://docs.oasis-open.org/ns/xri/xrd-1.0\"> <Link
rel=\"lrdd\"
template=\"https://hostux.social/.well-known/webfinger?resource={uri}\"/>
</XRD>
/.well-known/nodeinfo:
get:
tags:
- well-known
responses:
"200":
description: Prefix nodeinfo Controller#Action well_known/nodeinfo#index
{:format=>"json"}
content:
application/json:
schema:
$ref: "#/components/schemas/WellKnownNodeInfo"
/.well-known/webfinger:
get:
parameters:
- in: query
name: resource
required: true
description: query target (URI)
schema:
type: string
- in: query
name: rel
schema:
type: string
format: uri
tags:
- well-known
- jrd
responses:
"200":
description: Prefix webfinger Controller#Action well_known/webfinger#show
content:
application/jrd+json:
schema:
$ref: "#/components/schemas/WebFinger"
/.well-known/change-password:
get:
tags:
- well-known
responses:
"301":
description: Controller#Action redirect(301, /auth/edit)
content:
text/html:
example: ""
headers:
location:
schema:
type: string
example: https://hostux.social/auth/edit
/.well-known/keybase-proof-config:
get:
tags:
- well-known
responses:
"200":
description: Controller#Action well_known/keybase_proof_config#show
content:
application/json:
schema:
$ref: "#/components/schemas/KeybaseProofConfig"
/nodeinfo/2.0:
get:
responses:
"200":
description: Prefix nodeinfo_schema Controller#Action well_known/nodeinfo#show
content:
application/json:
schema:
$ref: "#/components/schemas/NodeInfo"
/manifest:
get:
responses:
"200":
description: Prefix manifest Controller#Action manifests#show {:format=>"json"}
content:
application/json:
schema:
$ref: "#/components/schemas/Manifest"
/intent:
get:
tags:
- todo
responses:
"200":
description: Prefix intent Controller#Action intents#show
/actor/inbox:
post:
tags:
- ActivityPub
- todo
responses:
"200":
description: Prefix instance_actor_inbox Controller#Action
activitypub/inboxes#create
/actor/outbox:
get:
tags:
- ActivityPub
responses:
"200":
description: Prefix instance_actor_outbox Controller#Action
activitypub/outboxes#show
content:
application/activity+json:
schema:
type: object
properties:
"@context":
type: string
id:
type: string
type:
type: string
totalItems:
type: integer
first:
type: string
last:
type: string
example:
"@context": https://www.w3.org/ns/activitystreams
id: http://localhost:3000/actor/outbox
type: OrderedCollection
totalItems: 0
first: http://localhost:3000/actor/outbox?page=true
last: http://localhost:3000/actor/outbox?min_id=0&page=true
/actor:
get:
tags:
- ActivityPub
- todo
responses:
"200":
description: ""
/invite/invite_code:
get:
tags:
- todo
responses:
"200":
description: ""
/auth/setup:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
patch:
tags:
- auth
- todo
responses:
"200":
description: ""
put:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/challenge:
post:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/sessions/security_key_options:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/sign_in:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
post:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/sign_out:
delete:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/password/new:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/password/edit:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/password:
patch:
tags:
- auth
- todo
responses:
"200":
description: ""
put:
tags:
- auth
- todo
responses:
"200":
description: ""
post:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/cancel:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/sign_up:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/edit:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth:
patch:
tags:
- auth
- todo
responses:
"200":
description: ""
put:
tags:
- auth
- todo
responses:
"200":
description: ""
delete:
tags:
- auth
- todo
responses:
"200":
description: ""
post:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/confirmation/new:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
/auth/confirmation:
get:
tags:
- auth
- todo
responses:
"200":
description: ""
post:
tags:
- auth
- todo
responses:
"200":
description: ""
/authorize_follow:
get:
tags:
- todo
responses:
"200":
description: ""
"/users/{account_username}/remote_follow":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: ""
post:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/statuses/{id}/activity":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: integer
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/statuses/{id}/embed":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: integer
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/statuses/{status_id}/replies":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: status_id
required: true
schema:
type: integer
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/statuses/{id}":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: integer
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/followers":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/following":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/follow":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
post:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/unfollow":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
post:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/outbox":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/inbox":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
post:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/claim":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
post:
tags:
- users
- todo
responses:
"200":
description: ""
"/users/{account_username}/collections/{id}":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: integer
get:
tags:
- users
- todo
responses:
"200":
description: OK
"/users/{account_username}/followers_synchronization":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: OK
"/users/{username}":
parameters:
- in: path
name: username
description: username of an account
required: true
schema:
type: string
get:
tags:
- users
- todo
responses:
"200":
description: ""
/inbox:
post:
tags:
- todo
responses:
"200":
description: ""
"/@{username}":
parameters:
- in: path
name: username
description: username of an account
required: true
schema:
type: string
get:
tags:
- todo
responses:
"200":
description: ""
"/@{username}/with_replies":
parameters:
- in: path
name: username
description: username of an account
required: true
schema:
type: string
get:
tags:
- todo
responses:
"200":
description: ""
"/@{username}/media":
parameters:
- in: path
name: username
description: username of an account
required: true
schema:
type: string
get:
tags:
- todo
responses:
"200":
description: ""
"/@{username}/tagged/{tag}":
parameters:
- in: path
name: username
description: username of an account
required: true
schema:
type: string
- in: path
name: tag
description: ""
required: true
schema:
type: string
get:
tags:
- todo
responses:
"200":
description: ""
"/@{account_username}/{id}":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
description: ""
required: true
schema:
type: integer
get:
tags:
- todo
responses:
"200":
description: ""
"/@{account_username}/{id}/embed":
parameters:
- in: path
name: account_username
description: username of an account
required: true
schema:
type: string
- in: path
name: id
description: ""
required: true
schema:
type: integer
get:
tags:
- todo
responses:
"200":
description: ""
"/interact/{id}":
parameters:
- in: path
name: id
description: ""
required: true
schema:
type: integer
get:
tags:
- todo
responses:
"200":
description: ""
post:
tags:
- todo
responses:
"200":
description: ""
/explore:
get:
tags:
- todo
responses:
"200":
description: ""
/settings:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings Controller#Action : redirect(301,
/settings/profile)"
"/settings/profile/pictures/{id}":
parameters:
- in: path
name: id
required: true
schema:
type: integer
delete:
tags:
- settings
- todo
responses:
"200":
description: "settings_profile_picture Controller#Action
settings/pictures#destroy"
/settings/profile:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_profile Controller#Action settings/profiles#show"
patch:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/profiles#update"
put:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/profiles#update"
/settings/preferences:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_preferences Controller#Action redirect(301,
/settings/preferences/appearance)"
/settings/preferences/appearance:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_preferences_appearance Controller#Action
settings/preferences/appearance#show"
patch:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/preferences/appearance#update"
put:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/preferences/appearance#update"
/settings/preferences/notifications:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_preferences_notifications Controller#Action
settings/preferences/notifications#show"
patch:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action
settings/preferences/notifications#update"
put:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action
settings/preferences/notifications#update"
/settings/preferences/other:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_preferences_other Controller#Action
settings/preferences/other#show"
patch:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/preferences/other#update"
put:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/preferences/other#update"
/settings/import:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_import Controller#Action settings/imports#show"
post:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/imports#create"
/settings/export:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_export Controller#Action settings/exports#show"
post:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action settings/exports#create"
/settings/exports/follows:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_follows Controller#Action
settings/exports/following_accounts#index {:format=>:csv}"
/settings/exports/blocks:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_blocks Controller#Action
settings/exports/blocked_accounts#index {:format=>:csv}"
/settings/exports/mutes:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_mutes Controller#Action
settings/exports/muted_accounts#index {:format=>:csv}"
/settings/exports/lists:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_lists Controller#Action
settings/exports/lists#index {:format=>:csv}"
/settings/exports/domain_blocks:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_domain_blocks Controller#Action
settings/exports/blocked_domains#index {:format=>:csv}"
/settings/exports/bookmarks:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_exports_bookmarks Controller#Action
settings/exports/bookmarks#index {:format=>:csv}"
/settings/two_factor_authentication_methods/disable:
post:
tags:
- settings
- todo
responses:
"200":
description: "disable_settings_two_factor_authentication_methods
Controller#Action
settings/two_factor_authentication_methods#disable"
/settings/two_factor_authentication_methods:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_two_factor_authentication_methods
Controller#Action settings/two_factor_authentication_methods#index"
/settings/otp_authentication:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_otp_authentication Controller#Action
settings/two_factor_authentication/otp_authentication#show"
post:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action
settings/two_factor_authentication/otp_authentication#create"
/settings/security_keys/options:
get:
tags:
- settings
- todo
responses:
"200":
description: "options_settings_webauthn_credentials Controller#Action
settings/two_factor_authentication/webauthn_credentials#options"
/settings/security_keys:
get:
tags:
- settings
- todo
responses:
"200":
description: "settings_webauthn_credentials Controller#Action
settings/two_factor_authentication/webauthn_credentials#index"
post:
tags:
- settings
- todo
responses:
"200":
description: "Controller#Action
settings/two_factor_authentication/webauthn_credentials#create"
/settings/security_keys/new:
get:
tags:
- settings
- todo
responses:
"200":
description: "new_settings_webauthn_credential Controller#Action
settings/two_factor_authentication/webauthn_credentials#new"
"/settings/security_keys/{id}":
parameters:
- in: path
name: id
required: true
schema:
type: integer
delete:
tags:
- settings
- todo
responses:
"200":
description: "settings_webauthn_credential Controller#Action
settings/two_factor_authentication/webauthn_credentials#destroy"
/settings/two_factor_authentication/recovery_codes:
post:
tags:
- settings
- todo
responses:
"200":
description: "settings_two_factor_authentication_recovery_codes
Controller#Action
settings/two_factor_authentication/recovery_codes#create"
/settings/two_factor_authentication/confirmation/new:
get:
tags:
- settings
- todo
responses:
"200":
description: "new_settings_two_factor_authentication_confirmation
Controller#Action
settings/two_factor_authentication/confirmations#
# --- truncated at 32 KB (161 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mastodon/refs/heads/main/openapi/mastodon.yml