2017-01-21 16:53:02 -05:00
API overview
============
## Contents
2017-01-21 16:49:08 -05:00
- [Available libraries ](#available-libraries )
- [Notes ](#notes )
- [Methods ](#methods )
2017-04-03 00:03:49 -04:00
- [Accounts ](#accounts )
- [Apps ](#apps )
- [Blocks ](#blocks )
- [Favourites ](#favourites )
- [Follow Requests ](#follow-requests )
- [Follows ](#follows )
- [Instances ](#instances )
- [Media ](#media )
- [Mutes ](#mutes )
- [Notifications ](#notifications )
- [Reports ](#reports )
- [Search ](#search )
- [Statuses ](#statuses )
- [Timelines ](#timelines )
2017-01-21 16:49:08 -05:00
- [Entities ](#entities )
2017-04-03 00:03:49 -04:00
- [Account ](#account )
- [Application ](#application )
- [Attachment ](#attachment )
- [Card ](#card )
- [Context ](#context )
- [Error ](#error )
- [Instance ](#instance )
- [Mention ](#mention )
- [Notification ](#notification )
- [Relationships ](#relationships )
- [Results ](#results )
- [Status ](#status )
- [Tag ](#tag )
___
2017-01-21 16:49:08 -05:00
2017-01-21 16:53:02 -05:00
## Available libraries
2017-01-21 16:49:08 -05:00
- [For Ruby ](https://github.com/tootsuite/mastodon-api )
- [For Python ](https://github.com/halcy/Mastodon.py )
- [For JavaScript ](https://github.com/Zatnosk/libodonjs )
- [For JavaScript (Node.js) ](https://github.com/jessicahayley/node-mastodon )
2017-04-08 03:48:52 -04:00
- [For Elixir ](https://github.com/milmazz/hunter )
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
___
2017-01-21 16:53:02 -05:00
## Notes
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### 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.
2017-01-21 16:49:08 -05:00
When a file parameter is mentioned, a form-encoded upload is expected.
2017-04-03 00:03:49 -04:00
### 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 ](https://tools.ietf.org/html/rfc5988 ) for more information.
### Errors
If the request you make doesn't go through, Mastodon will usually respond with an [Error ](#error ).
___
2017-01-21 16:53:02 -05:00
## Methods
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Accounts
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching an account:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an [Account ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Getting the current user:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/verify_credentials
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns the authenticated user's [Account ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-09 12:33:40 -04:00
#### Updating the current user:
PATCH /api/v1/accounts/update_credentials
Form data:
- `display_name` : The name to display in the user's profile
- `note` : A new biography for the user
- `avatar` : A base64 encoded image to display as the user's avatar (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...` )
- `header` : A base64 encoded image to display as the user's header image (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...` )
2017-04-03 00:03:49 -04:00
#### Getting an account's followers:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/followers
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Getting who account is following:
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/following
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ).
#### Getting an account's statuses:
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/statuses
2017-01-21 16:49:08 -05:00
Query parameters:
2017-04-03 00:03:49 -04:00
- `only_media` (optional): Only return statuses that have media attachments
- `exclude_replies` (optional): Skip statuses that reply to other statuses
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Statuses ](#status ).
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
#### Following/unfollowing an account:
2017-03-05 11:27:17 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/follow
GET /api/v1/accounts/:id/unfollow
2017-01-21 16:49:08 -05:00
2017-04-03 00:17:07 -04:00
Returns the target [Account ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Blocking/unblocking an account:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/block
GET /api/v1/accounts/:id/unblock
2017-01-29 06:53:50 -05:00
2017-04-03 00:17:07 -04:00
Returns the target [Account ](#account ).
2017-01-29 06:53:50 -05:00
2017-04-03 00:03:49 -04:00
#### Muting/unmuting an account:
2017-01-29 06:53:50 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/:id/mute
GET /api/v1/accounts/:id/unmute
2017-01-29 06:53:50 -05:00
2017-04-03 00:17:07 -04:00
Returns the target [Account ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Getting an account's relationships:
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/relationships
2017-04-03 00:03:49 -04:00
Query parameters:
- `id` (can be array): Account IDs
Returns an array of [Relationships ](#relationships ) of the current user to a list of given accounts.
#### Searching for accounts:
2017-04-03 00:13:15 -04:00
GET /api/v1/accounts/search
2017-04-03 00:03:49 -04:00
Query parameters:
- `q` : What to search for
- `limit` : Maximum number of matching accounts to return (default: `40` )
Returns an array of matching [Accounts ](#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:
2017-04-03 00:13:15 -04:00
POST /api/v1/apps
2017-01-21 16:49:08 -05:00
Form data:
2017-04-03 00:03:49 -04:00
- `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 ](OAuth-details.md ) for details on what the scopes do)
- `website` : (optional) URL to the homepage of your app
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Creates a new OAuth app.
Returns `id` , `client_id` and `client_secret` which can be used with [OAuth authentication in your 3rd party app ](Testing-with-cURL.md ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
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.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Blocks
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a user's blocks:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/blocks
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ) blocked by the authenticated user.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Favourites
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a user's favourites:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/favourites
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Statuses ](#status ) favourited by the authenticated user.
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
### Follow Requests
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a list of follow requests:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/follow_requests
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ) which have requested to follow the authenticated user.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Authorizing or rejecting follow requests:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
POST /api/v1/follow_requests/authorize
POST /api/v1/follow_requests/reject
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Form data:
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
- `id` : The id of the account to authorize or reject
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an empty object.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Follows
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Following a remote user:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
POST /api/v1/follows
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Form data:
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
- `uri` : `username@domain` of the person you want to follow
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns the local representation of the followed account, as an [Account ](#account ).
### Instances
#### Getting instance information:
2017-04-03 00:13:15 -04:00
GET /api/v1/instance
2017-04-03 00:03:49 -04:00
Returns the current [Instance ](#instance ).
Does not require authentication.
### Media
#### Uploading a media attachment:
2017-04-03 00:13:15 -04:00
POST /api/v1/media
2017-04-03 00:03:49 -04:00
Form data:
- `file` : Media to be uploaded
Returns an [Attachment ](#attachment ) that can be used when creating a status.
### Mutes
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a user's mutes:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/mutes
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ) muted by the authenticated user.
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
### Notifications
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a user's notifications:
2017-03-05 11:27:17 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/notifications
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns a list of [Notifications ](#notification ) for the authenticated user.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Getting a single notification:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/notifications/:id
2017-04-03 00:03:49 -04:00
Returns the [Notification ](#notification ).
#### Clearing notifications:
2017-04-03 00:13:15 -04:00
POST /api/v1/notifications/clear
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Deletes all notifications from the Mastodon server for the authenticated user.
2017-01-21 16:49:08 -05:00
Returns an empty object.
2017-04-03 00:03:49 -04:00
### Reports
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Fetching a user's reports:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/reports
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns a list of [Reports ](#report ) made by the authenticated user.
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Reporting a user:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
POST /api/v1/reports
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Form data:
- `account_id` : The ID of the account to report
- `status_ids` : The IDs of statuses to report (can be an array)
- `comment` : A comment to associate with the report.
Returns the finished [Report ](#report ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Search
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Searching for content:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/search
2017-04-03 00:03:49 -04:00
Form data:
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
- `q` : The search query
- `resolve` : Whether to resolve non-local accounts
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns [Results ](#results ).
If `q` is a URL, Mastodon will attempt to fetch the provided account or status.
Otherwise, it will do a local account and hashtag search.
### Statuses
#### Fetching a status:
2017-04-03 00:13:15 -04:00
GET /api/v1/statuses/:id
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns a [Status ](#status ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Getting status context:
2017-01-21 16:49:08 -05:00
2017-04-05 04:25:05 -04:00
GET /api/v1/statuses/:id/context
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns a [Context ](#context ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:17:07 -04:00
#### Getting a card associated with a status:
2017-04-03 00:03:49 -04:00
2017-04-03 00:13:15 -04:00
GET /api/v1/statuses/:id/card
2017-04-03 00:03:49 -04:00
Returns a [Card ](#card ).
#### Getting who reblogged/favourited a status:
2017-04-03 00:13:15 -04:00
GET /api/v1/statuses/:id/reblogged_by
GET /api/v1/statuses/:id/favourited_by
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns an array of [Accounts ](#account ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Posting a new status:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
POST /api/v1/statuses
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Form data:
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
- `status` : The text of the status
- `in_reply_to_id` (optional): local ID of the status you want to reply to
- `media_ids` (optional): array of media IDs to attach to the status (maximum 4)
- `sensitive` (optional): set this to mark the media of the status as NSFW
- `spoiler_text` (optional): text to be shown as a warning before the actual content
2017-04-03 04:23:37 -04:00
- `visibility` (optional): either "direct", "private", "unlisted" or "public"
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns the new [Status ](#status ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Deleting a status:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
DELETE /api/v1/statuses/:id
2017-02-27 07:06:25 -05:00
2017-04-03 00:03:49 -04:00
Returns an empty object.
2017-02-27 07:06:25 -05:00
2017-04-03 00:03:49 -04:00
#### Reblogging/unreblogging a status:
2017-02-27 07:06:25 -05:00
2017-04-03 00:13:15 -04:00
POST /api/vi/statuses/:id/reblog
POST /api/vi/statuses/:id/unreblog
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
Returns the target [Status ](#status ).
2017-03-05 11:27:17 -05:00
2017-04-03 00:03:49 -04:00
#### Favouriting/unfavouriting a status:
2017-03-05 11:27:17 -05:00
2017-04-03 00:13:15 -04:00
POST /api/vi/statuses/:id/favourite
POST /api/vi/statuses/:id/unfavourite
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Returns the target [Status ](#status ).
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Timelines
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
#### Retrieving a timeline:
2017-01-21 16:49:08 -05:00
2017-04-03 00:13:15 -04:00
GET /api/v1/timelines/home
GET /api/v1/timelines/public
GET /api/v1/timelines/tag/:hashtag
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
Query parameters:
2017-01-25 12:31:15 -05:00
2017-04-03 00:03:49 -04:00
- `local` (optional; public and tag timelines only): Only return statuses originating from this instance
Returns an array of [Statuses ](#status ), most recent ones first.
2017-01-21 16:49:08 -05:00
___
2017-01-21 16:53:02 -05:00
## Entities
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Account
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
| Attribute | Description |
| ------------------------ | ----------- |
| `id` | The ID of the account |
| `username` | The username of the account |
| `acct` | Equals `username` for local users, includes `@domain` for remote ones |
| `display_name` | The account's display name |
| `note` | Biography of user |
| `url` | URL of the user's profile page (can be remote) |
| `avatar` | URL to the avatar image |
| `header` | URL to the header image |
| `locked` | Boolean for when the account cannot be followed without waiting for approval first |
| `created_at` | The time the account was created |
| `followers_count` | The number of followers for the account |
| `following_count` | The number of accounts the given account is following |
| `statuses_count` | The number of statuses the account has made |
### Application
| Attribute | Description |
| ------------------------ | ----------- |
| `name` | Name of the app |
| `website` | Homepage URL of the app |
### Attachment
| Attribute | Description |
| ------------------------ | ----------- |
| `id` | ID of the attachment |
| `type` | One of: "image", "video", "gifv" |
| `url` | URL of the locally hosted version of the image |
| `remote_url` | For remote images, the remote URL of the original image |
| `preview_url` | URL of the preview image |
| `text_url` | Shorter URL for the image, for insertion into text (only present on local images) |
### Card
| Attribute | Description |
| ------------------------ | ----------- |
2017-04-03 00:17:07 -04:00
| `url` | The url associated with the card |
2017-04-03 00:03:49 -04:00
| `title` | The title of the card |
| `description` | The card description |
| `image` | The image associated with the card, if any |
### Context
| Attribute | Description |
| ------------------------ | ----------- |
| `ancestors` | The ancestors of the status in the conversation, as a list of [Statuses ](#status ) |
| `descendants` | The descendants of the status in the conversation, as a list of [Statuses ](#status ) |
### Error
| Attribute | Description |
| ------------------------ | ----------- |
| `error` | A textual description of the error |
### Instance
| Attribute | Description |
| ------------------------ | ----------- |
| `uri` | URI of the current instance |
| `title` | The instance's title |
| `description` | A description for the instance |
| `email` | An email address which can be used to contact the instance administrator |
### Mention
| Attribute | Description |
| ------------------------ | ----------- |
| `url` | URL of user's profile (can be remote) |
| `username` | The username of the account |
| `acct` | Equals `username` for local users, includes `@domain` for remote ones |
| `id` | Account ID |
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
### Notifications
| Attribute | Description |
| ------------------------ | ----------- |
| `id` | The notification ID |
| `type` | One of: "mention", "reblog", "favourite", "follow" |
| `created_at` | The time the notification was created |
| `account` | The [Account ](#account ) sending the notification to the user |
| `status` | The [Status ](#status ) associated with the notification, if applicible |
### Relationships
| Attribute | Description |
| ------------------------ | ----------- |
| `following` | Whether the user is currently following the account |
| `followed_by` | Whether the user is currently being followed by the account |
| `blocking` | Whether the user is currently blocking the account |
| `muting` | Whether the user is currently muting the account |
| `requested` | Whether the user has requested to follow the account |
### Report
| Attribute | Description |
| ------------------------ | ----------- |
| `id` | The ID of the report |
| `action_taken` | The action taken in response to the report |
### Results
| Attribute | Description |
| ------------------------ | ----------- |
| `accounts` | An array of matched [Accounts ](#account ) |
| `statuses` | An array of matchhed [Statuses ](#status ) |
| `hashtags` | An array of matched hashtags, as strings |
### Status
2017-01-21 16:49:08 -05:00
2017-04-03 00:03:49 -04:00
| Attribute | Description |
| ------------------------ | ----------- |
| `id` | The ID of the status |
| `uri` | A Fediverse-unique resource ID |
| `url` | URL to the status page (can be remote) |
| `account` | The [Account ](#account ) which posted the status |
| `in_reply_to_id` | `null` or the ID of the status it replies to |
| `in_reply_to_account_id` | `null` or the ID of the account it replies to |
| `reblog` | `null` or the reblogged [Status ](#status ) |
| `content` | Body of the status; this will contain HTML (remote HTML already sanitized) |
| `created_at` | The time the status was created |
| `reblogs_count` | The number of reblogs for the status |
| `favourites_count` | The number of favourites for the status |
| `reblogged` | Whether the authenticated user has reblogged the status |
| `favourited` | Whether the authenticated user has favourited the status |
| `sensitive` | Whether media attachments should be hidden by default |
| `spoiler_text` | If not empty, warning text that should be displayed before the actual content |
2017-04-03 01:46:10 -04:00
| `visibility` | One of: `public` , `unlisted` , `private` , `direct` |
2017-04-03 00:03:49 -04:00
| `media_attachments` | An array of [Attachments ](#attachment ) |
| `mentions` | An array of [Mentions ](#mention ) |
| `tags` | An array of [Tags ](#tag ) |
| `application` | [Application ](#application ) from which the status was posted |
### Tags
| Attribute | Description |
| ------------------------ | ----------- |
| `name` | The hashtag, not including the preceding `#` |
| `url` | The URL of the hashtag |