forked from asonix/mastodon
524 lines
15 KiB
Markdown
524 lines
15 KiB
Markdown
API overview
|
|
============
|
|
|
|
## Contents
|
|
|
|
- [Available libraries](#available-libraries)
|
|
- [Notes](#notes)
|
|
- [Methods](#methods)
|
|
- [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)
|
|
- [Entities](#entities)
|
|
- [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)
|
|
|
|
___
|
|
|
|
## Available libraries
|
|
|
|
- [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)
|
|
|
|
___
|
|
|
|
## 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](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).
|
|
|
|
___
|
|
|
|
## Methods
|
|
|
|
### Accounts
|
|
|
|
#### Fetching an account:
|
|
|
|
GET /api/v1/accounts/:id
|
|
|
|
Returns an [Account](#account).
|
|
|
|
#### Getting the current user:
|
|
|
|
GET /api/v1/accounts/verify_credentials
|
|
|
|
Returns the authenticated user's [Account](#account).
|
|
|
|
#### Getting an account's followers:
|
|
|
|
GET /api/v1/accounts/:id/followers
|
|
|
|
Returns an array of [Accounts](#account).
|
|
|
|
#### Getting who account is following:
|
|
|
|
GET /api/v1/accounts/:id/following
|
|
|
|
Returns an array of [Accounts](#account).
|
|
|
|
#### 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](#status).
|
|
|
|
#### Following/unfollowing an account:
|
|
|
|
GET /api/v1/accounts/:id/follow
|
|
GET /api/v1/accounts/:id/unfollow
|
|
|
|
Returns the target [Account](#account).
|
|
|
|
#### Blocking/unblocking an account:
|
|
|
|
GET /api/v1/accounts/:id/block
|
|
GET /api/v1/accounts/:id/unblock
|
|
|
|
Returns the target [Account](#account).
|
|
|
|
#### Muting/unmuting an account:
|
|
|
|
GET /api/v1/accounts/:id/mute
|
|
GET /api/v1/accounts/:id/unmute
|
|
|
|
Returns the target [Account](#account).
|
|
|
|
#### Getting an account's relationships:
|
|
|
|
GET /api/v1/accounts/relationships
|
|
|
|
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:
|
|
|
|
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](#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](OAuth-details.md) 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](Testing-with-cURL.md).
|
|
|
|
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](#account) blocked by the authenticated user.
|
|
|
|
### Favourites
|
|
|
|
#### Fetching a user's favourites:
|
|
|
|
GET /api/v1/favourites
|
|
|
|
Returns an array of [Statuses](#status) favourited by the authenticated user.
|
|
|
|
### Follow Requests
|
|
|
|
#### Fetching a list of follow requests:
|
|
|
|
GET /api/v1/follow_requests
|
|
|
|
Returns an array of [Accounts](#account) 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](#account).
|
|
|
|
### Instances
|
|
|
|
#### Getting instance information:
|
|
|
|
GET /api/v1/instance
|
|
|
|
Returns the current [Instance](#instance).
|
|
Does not require authentication.
|
|
|
|
### Media
|
|
|
|
#### Uploading a media attachment:
|
|
|
|
POST /api/v1/media
|
|
|
|
Form data:
|
|
|
|
- `file`: Media to be uploaded
|
|
|
|
Returns an [Attachment](#attachment) that can be used when creating a status.
|
|
|
|
### Mutes
|
|
|
|
#### Fetching a user's mutes:
|
|
|
|
GET /api/v1/mutes
|
|
|
|
Returns an array of [Accounts](#account) muted by the authenticated user.
|
|
|
|
### Notifications
|
|
|
|
#### Fetching a user's notifications:
|
|
|
|
GET /api/v1/notifications
|
|
|
|
Returns a list of [Notifications](#notification) for the authenticated user.
|
|
|
|
#### Getting a single notification:
|
|
|
|
GET /api/v1/notifications/:id
|
|
|
|
Returns the [Notification](#notification).
|
|
|
|
#### Clearing notifications:
|
|
|
|
POST /api/v1/notifications/clear
|
|
|
|
Deletes all notifications from the Mastodon server for the authenticated user.
|
|
Returns an empty object.
|
|
|
|
### Reports
|
|
|
|
#### Fetching a user's reports:
|
|
|
|
GET /api/v1/reports
|
|
|
|
Returns a list of [Reports](#report) made by the authenticated user.
|
|
|
|
#### Reporting a user:
|
|
|
|
POST /api/v1/reports
|
|
|
|
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).
|
|
|
|
### Search
|
|
|
|
#### Searching for content:
|
|
|
|
GET /api/v1/search
|
|
|
|
Form data:
|
|
|
|
- `q`: The search query
|
|
- `resolve`: Whether to resolve non-local accounts
|
|
|
|
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:
|
|
|
|
GET /api/v1/statuses/:id
|
|
|
|
Returns a [Status](#status).
|
|
|
|
#### Getting status context:
|
|
|
|
GET /api/v1/statuses/:id/contexts
|
|
|
|
Returns a [Context](#context).
|
|
|
|
#### Getting a card associated with a status:
|
|
|
|
GET /api/v1/statuses/:id/card
|
|
|
|
Returns a [Card](#card).
|
|
|
|
#### Getting who reblogged/favourited a status:
|
|
|
|
GET /api/v1/statuses/:id/reblogged_by
|
|
GET /api/v1/statuses/:id/favourited_by
|
|
|
|
Returns an array of [Accounts](#account).
|
|
|
|
#### Posting a new status:
|
|
|
|
POST /api/v1/statuses
|
|
|
|
Form data:
|
|
|
|
- `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
|
|
- `visibility` (optional): either "direct", "private", "unlisted" or "public"
|
|
|
|
Returns the new [Status](#status).
|
|
|
|
#### Deleting a status:
|
|
|
|
DELETE /api/v1/statuses/:id
|
|
|
|
Returns an empty object.
|
|
|
|
#### Reblogging/unreblogging a status:
|
|
|
|
POST /api/vi/statuses/:id/reblog
|
|
POST /api/vi/statuses/:id/unreblog
|
|
|
|
Returns the target [Status](#status).
|
|
|
|
#### Favouriting/unfavouriting a status:
|
|
|
|
POST /api/vi/statuses/:id/favourite
|
|
POST /api/vi/statuses/:id/unfavourite
|
|
|
|
Returns the target [Status](#status).
|
|
|
|
### Timelines
|
|
|
|
#### Retrieving a timeline:
|
|
|
|
GET /api/v1/timelines/home
|
|
GET /api/v1/timelines/public
|
|
GET /api/v1/timelines/tag/:hashtag
|
|
|
|
Query parameters:
|
|
|
|
- `local` (optional; public and tag timelines only): Only return statuses originating from this instance
|
|
|
|
Returns an array of [Statuses](#status), most recent ones first.
|
|
___
|
|
|
|
## Entities
|
|
|
|
### Account
|
|
|
|
| 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 |
|
|
| ------------------------ | ----------- |
|
|
| `url` | The url associated with the card |
|
|
| `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 |
|
|
|
|
### 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
|
|
|
|
| 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 |
|
|
| `visibility` | One of: `public`, `unlisted`, `private`, `direct` |
|
|
| `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 |
|