API.md

API overview

Contents

• Available libraries
• Notes
• Methods
  • Accounts
  • Apps
  • Blocks
  • Favourites
  • Follow Requests
  • Follows
  • Instances
  • Media
  • Mutes
  • Notifications
  • Reports
  • Search
  • Statuses
  • Timelines
• Entities
  • Account
  • Application
  • Attachment
  • Card
  • Context
  • Error
  • Instance
  • Mention
  • Notification
  • Relationships
  • Results
  • Status
  • Tag

---

Available libraries

• For Ruby
• For Python
• For JavaScript
• For JavaScript (Node.js)
• For Elixir

---

Notes

Parameter types

When an array parameter is mentioned, the Rails convention of specifying array parameters in query strings is meant. For example, a ruby array like foo = [1, 2, 3] can be encoded in the params as foo[]=1&foo[]=2&foo[]=3. Square brackets can be indexed but can also be empty.

When a file parameter is mentioned, a form-encoded upload is expected.

Selecting ranges

For most GET operations that return arrays, the query parameters max_id and since_id can be used to specify the range of IDs to return. API methods that return collections of items can return a Link header containing URLs for the next and prev pages. See the Link header RFC for more information.

Errors

If the request you make doesn't go through, Mastodon will usually respond with an Error.

---

Methods

Accounts

Fetching an account:

GET /api/v1/accounts/:id

Returns an Account.

Getting the current user:

GET /api/v1/accounts/verify_credentials

Returns the authenticated user's Account.

Getting an account's followers:

GET /api/v1/accounts/:id/followers

Returns an array of Accounts.

Getting who account is following:

GET /api/v1/accounts/:id/following

Returns an array of Accounts.

Getting an account's statuses:

GET /api/v1/accounts/:id/statuses

Query parameters:

• only_media (optional): Only return statuses that have media attachments
• exclude_replies (optional): Skip statuses that reply to other statuses

Returns an array of Statuses.

Following/unfollowing an account:

GET /api/v1/accounts/:id/follow
GET /api/v1/accounts/:id/unfollow

Returns the target Account.

Blocking/unblocking an account:

GET /api/v1/accounts/:id/block
GET /api/v1/accounts/:id/unblock

Returns the target Account.

Muting/unmuting an account:

GET /api/v1/accounts/:id/mute
GET /api/v1/accounts/:id/unmute

Returns the target Account.

Getting an account's relationships:

GET /api/v1/accounts/relationships

Query parameters:

• id (can be array): Account IDs

Returns an array of Relationships of the current user to a list of given accounts.

Searching for accounts:

GET /api/v1/accounts/search

Query parameters:

• q: What to search for
• limit: Maximum number of matching accounts to return (default: 40)

Returns an array of matching Accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database.

Apps

Registering an application:

POST /api/v1/apps

Form data:

• client_name: Name of your application
• redirect_uris: Where the user should be redirected after authorization (for no redirect, use urn:ietf:wg:oauth:2.0:oob)
• scopes: This can be a space-separated list of the following items: "read", "write" and "follow" (see this page for details on what the scopes do)
• website: (optional) URL to the homepage of your app

Creates a new OAuth app. Returns id, client_id and client_secret which can be used with OAuth authentication in your 3rd party app.

These values should be requested in the app itself from the API for each new app install + mastodon domain combo, and stored in the app for future requests.

Blocks

Fetching a user's blocks:

GET /api/v1/blocks

Returns an array of Accounts blocked by the authenticated user.

Favourites

Fetching a user's favourites:

GET /api/v1/favourites

Returns an array of Statuses favourited by the authenticated user.

Follow Requests

Fetching a list of follow requests:

GET /api/v1/follow_requests

Returns an array of Accounts which have requested to follow the authenticated user.

Authorizing or rejecting follow requests:

POST /api/v1/follow_requests/authorize
POST /api/v1/follow_requests/reject

Form data:

• id: The id of the account to authorize or reject

Returns an empty object.

Follows

Following a remote user:

POST /api/v1/follows

Form data:

• uri: username@domain of the person you want to follow

Returns the local representation of the followed account, as an Account.

Instances

Getting instance information:

GET /api/v1/instance

Returns the current Instance. Does not require authentication.

Media

Uploading a media attachment:

POST /api/v1/media

Form data:

• file: Media to be uploaded

Returns an Attachment that can be used when creating a status.

Mutes

Fetching a user's mutes:

GET /api/v1/mutes

Returns an array of Accounts muted by the authenticated user.

Notifications

Fetching a user's notifications: