instrumental/docs/Using-the-API/API.md

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 status card:

    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 `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 of the associated status |
| `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` |
| `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 |