documentation/Using-the-API/API.md

API overview
============

## Contents

- [Available libraries](#available-libraries)
- [Notes](#notes)
- [Methods](#methods)
  - [Accounts](#accounts)
  - [Apps](#apps)
  - [Blocks](#blocks)
  - [Domain blocks](#domain-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)
  - [Lists](#lists)
- [Entities](#entities)
  - [Account](#account)
  - [Application](#application)
  - [Attachment](#attachment)
  - [Card](#card)
  - [Context](#context)
  - [Emoji](#emoji)
  - [Error](#error)
  - [Instance](#instance)
  - [Mention](#mention)
  - [Notification](#notification)
  - [Relationship](#relationship)
  - [Results](#results)
  - [Status](#status)
  - [Tag](#tag)
  - [List](#list)

___

## Available libraries

There are several libraries to interact with the Mastodon API. The list of libraries can be found on the [Libraries page](Libraries.md).

___

## 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]` should be encoded in the params as `foo[]=1&foo[]=2&foo[]=3`, with empty square brackets.

When sending binary data, such as files, Mastodon expects clients to use the `multipart/form-data` MIME type. This applies to media attachments, account avatars and account headers.

###### 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) with an extra attribute `source` which contains these keys:

| Attribute   | Description                                              |
| ----------- | -------------------------------------------------------- |
| `privacy`   | Selected preference: Default privacy of new toots        |
| `sensitive` | Selected preference: Mark media as sensitive by default? |
| `note`      | Plain-text version of the account's `note`               |

#### Updating the current user:

    PATCH /api/v1/accounts/update_credentials

Form data:

| Field          | Description                                                       | Optional   |
| -------------- | ----------------------------------------------------------------- | ---------- |
| `display_name` | The name to display in the user's profile                         | yes        |
| `note`         | A new biography for the user                                      | yes        |
| `avatar`       | An avatar for the user (encoded using `multipart/form-data`)      | yes        |
| `header`       | A header image for the user (encoded using `multipart/form-data`) | yes        |

Returns the authenticated user's [Account](#account).

#### Getting an account's followers:

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

Query parameters:

| Field      | Description                                                    | Optional   |
| ---------- | -------------------------------------------------------------- | ---------- |
| `max_id`   | Get a list of followers with ID less than this value           | yes        |
| `since_id` | Get a list of followers with ID greater than this value        | yes        |
| `limit`    | Maximum number of followers to get (Default 40, Max 80)        | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account).

#### Getting who account is following:

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

Query parameters:

| Field      | Description                                                    | Optional   |
| ---------- | -------------------------------------------------------------- | ---------- |
| `max_id`   | Get a list of followings with ID less than this value          | yes        |
| `since_id` | Get a list of followings with ID greater than this value       | yes        |
| `limit`    | Maximum number of followings to get (Default 40, Max 80)       | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account).

#### Getting an account's statuses:

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

Query parameters:

| Field             | Description                                                  | Optional   |
| ----------------- | -----------------------------------------------------------  | ---------- |
| `only_media`      | Only return statuses that have media attachments             | yes        |
| `pinned`          | Only return statuses that have been pinned                   | yes        |
| `exclude_replies` | Skip statuses that reply to other statuses                   | yes        |
| `max_id`          | Get a list of statuses with ID less than this value          | yes        |
| `since_id`        | Get a list of statuses with ID greater than this value       | yes        |
| `limit`           | Maximum number of statuses to get (Default 20, Max 40)       | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. However, it is possible to use the `id` of the returned objects to construct your own URLs.

Returns an array of [Statuses](#status).

#### Following/unfollowing an account:

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

Returns the target account's [Relationship](#relationship).

#### Blocking/unblocking an account:

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

Returns the target account's [Relationship](#relationship).

#### Muting/unmuting an account:

    POST /api/v1/accounts/:id/mute
    
    Form data:

| Field          | Description                               | Optional   |
| -------------- | ----------------------------------------- | ---------- |
| `notifications` | Determines whether the mute will mute notifications or not. Default(true) | yes        |

Returns the target account's [Relationship](#relationship).
    
    POST /api/v1/accounts/:id/unmute

Returns the target account's [Relationship](#relationship).

#### Getting an account's relationships:

    GET /api/v1/accounts/relationships

Query parameters:

| Field | Description                   | Optional   |
| ----- | ----------------------------  | ---------- |
| `id`  | Account IDs (can be an array) | no         |

Returns an array of [Relationships](#relationship) of the current user to a list of given accounts.

#### Searching for accounts:

    GET /api/v1/accounts/search

Query parameters:

| Field             | Description                                                   | Optional   |
| ----------------- | ------------------------------------------------------------- | ---------- |
| `q`               | What to search for                                            | no         |
| `limit`           | Maximum number of matching accounts to return (default: `40`) | yes        |

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:

| Field             | Description                                                                                                                                                   | Optional   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `client_name`     | Name of your application                                                                                                                                      | no         |
| `redirect_uris`   | Where the user should be redirected after authorization (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`)                                                    | no         |
| `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) | no         |
| `website`         | URL to the homepage of your app                                                                                                                               | yes        |

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

Query parameters:

| Field             | Description                                                   | Optional   |
| ----------------- | ------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of blocks with ID less than this value             | yes        |
| `since_id`        | Get a list of blocks with ID greater than this value          | yes        |
| `limit`           | Maximum number of blocks to get (Default 40, Max 80)          | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account) blocked by the authenticated user.

### Domain blocks

#### Fetching a user's blocked domains:

    GET /api/v1/domain_blocks

Query parameters:

| Field             | Description                                                   | Optional   |
| ----------------- | ------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of blocks with ID less than this value             | yes        |
| `since_id`        | Get a list of blocks with ID greater than this value          | yes        |
| `limit`           | Maximum number of blocks to get (Default 40, Max 80)          | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of strings.

#### Blocking a domain

    POST /api/v1/domain_blocks

Parameters:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `domain`          | Domain to block                                                     | no         |

Returns an empty object.

#### Unblocking a domain

    DELETE /api/v1/domain_blocks

Parameters:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `domain`          | Domain to unblock                                                   | no         |

Returns an empty object.

### Favourites

#### Fetching a user's favourites:

    GET /api/v1/favourites

Query parameters:

| Field             | Description                                                    | Optional   |
| ----------------- | -------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of favourites with ID less than this value          | yes        |
| `since_id`        | Get a list of favourites with ID greater than this value       | yes        |
| `limit`           | Maximum number of favourites to get (Default 20, Max 40)       | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Statuses](#status) favourited by the authenticated user.

### Follow Requests

#### Fetching a list of follow requests:

    GET /api/v1/follow_requests

Query parameters:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of follow requests with ID less than this value          | yes        |
| `since_id`        | Get a list of follow requests with ID greater than this value       | yes        |
| `limit`           | Maximum number of requests to get (Default 40, Max 80)              | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account) which have requested to follow the authenticated user.

#### Authorizing or rejecting follow requests:

    POST /api/v1/follow_requests/:id/authorize
    POST /api/v1/follow_requests/:id/reject

Returns an empty object.

### Follows

#### Following a remote user:

    POST /api/v1/follows

Form data:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `uri`             | `username@domain` of the person you want to follow                  | no         |

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:

| Field             | Description                                                               | Optional   |
| ----------------- | ------------------------------------------------------------------------- | ---------- |
| `file`            | Media to be uploaded (encoded using `multipart/form-data`)                | no         |
| `description`     | A plain-text description of the media, for accessibility (max 420 chars)  | yes        |

Returns an [Attachment](#attachment) that can be used when creating a status.

### Mutes

#### Fetching a user's mutes:

    GET /api/v1/mutes

Query parameters:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of mutes with ID less than this value                    | yes        |
| `since_id`        | Get a list of mutes with ID greater than this value                 | yes        |
| `limit`           | Maximum number of mutes to get (Default 40, Max 80)                 | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account) muted by the authenticated user.

### Notifications

#### Fetching a user's notifications:

    GET /api/v1/notifications

Query parameters:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `max_id`          | Get a list of notifications with ID less than this value            | yes        |
| `since_id`        | Get a list of notifications with ID greater than this value         | yes        |
| `limit`           | Maximum number of notifications to get (Default 15, Max 30)         | yes        |
| `exclude_types`   | Array of notifications to exclude (Allowed values: "follow", "favourite", "reblog", "mention")          | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. However, it is possible to use the `id` of the returned objects to construct your own URLs.

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.

#### Dismissing a single notification:

    POST /api/v1/notifications/dismiss
    
Form data:

| Field | Description                   | Optional   |
| ----- | ----------------------------  | ---------- |
| `id`  | Notification ID | no         |    

Deletes a single notification 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. (This method is not entirely implemented and contains no useful information at this point)

#### Reporting a user:

    POST /api/v1/reports

Form data:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `account_id`      | The ID of the account to report                                     | no         |
| `status_ids`      | The IDs of statuses to report (can be an array)                     | no         |
| `comment`         | A comment to associate with the report (up to 1000 characters)      | no         |

Returns the finished [Report](#report).

### Search

#### Searching for content:

    GET /api/v1/search

Form data:

| Field             | Description                                                         | Optional   |
| ----------------- | ------------------------------------------------------------------- | ---------- |
| `q`               | The search query                                                    | no         |
| `resolve`         | Whether to resolve non-local accounts (default: don't resolve)      | yes        |

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).

Does not require authentication.

#### Getting status context:

    GET /api/v1/statuses/:id/context

Returns a [Context](#context).

Does not require authentication.

#### Getting a card associated with a status:

    GET /api/v1/statuses/:id/card

Returns a [Card](#card).

Does not require authentication.

#### Getting who reblogged/favourited a status:

    GET /api/v1/statuses/:id/reblogged_by
    GET /api/v1/statuses/:id/favourited_by

Query parameters:

| Field             | Description                                                              | Optional   |
| ----------------- | ------------------------------------------------------------------------ | ---------- |
| `max_id`          | Get a list of reblogged/favourited with ID less than this value          | yes        |
| `since_id`        | Get a list of reblogged/favourited with ID greater than this value       | yes        |
| `limit`           | Maximum number of reblogged/favourited to get (Default 40, Max 80)       | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. It is **not** possible to use the `id` of the returned objects to construct your own URLs, because the results are sorted by an internal key.

Returns an array of [Accounts](#account).

Does not require authentication.


#### Fetching custom emoji for an instance:

    GET /api/v1/custom_emojis

Returns a list of [Emoji](#emoji)

Does not require authentication.

#### Posting a new status:

    POST /api/v1/statuses

Form data:

| Field             | Description                                                              | Optional   |
| ----------------- | ------------------------------------------------------------------------ | ---------- |
| `status`          | The text of the status                                                   | no         |
| `in_reply_to_id`  | local ID of the status you want to reply to                              | yes        |
| `media_ids`       | [Array](#parameter-types) of media IDs to attach to the status (maximum 4)                   | yes        |
| `sensitive`       | Set this to mark the media of the status as NSFW                         | yes        |
| `spoiler_text`    | Text to be shown as a warning before the actual content                  | yes        |
| `visibility`       | Either "direct", "private", "unlisted" or "public"                      | yes        |

Returns the new [Status](#status).

#### Deleting a status:

    DELETE /api/v1/statuses/:id

Returns an empty object.

#### Reblogging/unreblogging a status:

    POST /api/v1/statuses/:id/reblog
    POST /api/v1/statuses/:id/unreblog

Reblog: Returns the reblog [Status](#status).

Unreblog: Returns the target [Status](#status).

#### Favouriting/unfavouriting a status:

    POST /api/v1/statuses/:id/favourite
    POST /api/v1/statuses/:id/unfavourite

Returns the target [Status](#status).

#### Pinning/unpinning a status:

    POST /api/v1/statuses/:id/pin
    POST /api/v1/statuses/:id/unpin

Returns the target [Status](#status).

#### Muting/unmuting a conversation of a status

    POST /api/v1/statuses/:id/mute
    POST /api/v1/statuses/:id/unmute

Only makes sense for statuses featured inside notifications directed at the user. Muting a status will prevent replies to it, favourites and replies of it from appearing in the user's notifications.

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
    GET /api/v1/timelines/list/:list_id

Query parameters:

| Field             | Description                                                                         | Optional   |
| ----------------- | ----------------------------------------------------------------------------------- | ---------- |
| `local`           | Only return statuses originating from this instance (public and tag timelines only) | yes        |
| `max_id`          | Get a list of timelines with ID less than this value                                | yes        |
| `since_id`        | Get a list of timelines with ID greater than this value                             | yes        |
| `limit`           | Maximum number of statuses on the requested timeline to get (Default 20, Max 40)    | yes        |

> **Note:** `max_id` and `since_id` for next and previous pages are provided in the `Link` header. However, it is possible to use the `id` of the returned objects to construct your own URLs.

Returns an array of [Statuses](#status), most recent ones first.

Public and tag timelines do not require authentication.

### Lists

#### Retrieving lists

    GET /api/v1/lists

Returns at most 50 [Lists](#list) without pagination.

#### Retrieving lists by membership

    GET /api/v1/accounts/:id/lists
    
Returns at most 50 [Lists](#list) without pagination.

#### Retrieving accounts in a list

    GET /api/v1/lists/:id/accounts

Returns [Accounts](#account) in the list. If you specify `limit=0` in the query, all accounts will be returned without pagination. Otherwise, standard account pagination rules apply.

#### Retrieving, creating, updating, deleting a list

    GET /api/v1/lists/:id
    POST /api/v1/lists
    PUT /api/v1/lists/:id
    DELETE /api/v1/lists/:id

Form data:

| Field            | Description           | Optional  |
| ---------------- | --------------------- | --------- |
| `title`          | The title of the list | no        |

> **Note:** There is a limit of 50 lists.

#### Adding/removing accounts to/from a list

    POST /api/v1/lists/:id/accounts
    DELETE /api/v1/lists/:id/accounts

Form data:

| Field            | Description                               | Optional  |
| ---------------- | ----------------------------------------- | --------- |
| `account_ids`    | [Array](#parameter-types) of account IDs  | no        |

> **Note:** Only accounts already followed by the authenticated user can be added to a list.

___

## Entities

> **Note:** Some attributes in the entity payload can have ``null`` value and are marked as _nullable_ on the tables below. Attributes that are not nullable are guaranteed to return a valid value.

### Account

| Attribute                | Description                                                                        | Nullable |
| ------------------------ | ---------------------------------------------------------------------------------- | -------- |
| `id`                     | The ID of the account                                                              | no       |
| `username`               | The username of the account                                                        | no       |
| `acct`                   | Equals `username` for local users, includes `@domain` for remote ones              | no       |
| `display_name`           | The account's display name                                                         | no       |
| `locked`                 | Boolean for when the account cannot be followed without waiting for approval first | no       |
| `created_at`             | The time the account was created                                                   | no       |
| `followers_count`        | The number of followers for the account                                            | no       |
| `following_count`        | The number of accounts the given account is following                              | no       |
| `statuses_count`         | The number of statuses the account has made                                        | no       |
| `note`                   | Biography of user                                                                  | no       |
| `url`                    | URL of the user's profile page (can be remote)                                     | no       |
| `avatar`                 | URL to the avatar image                                                            | no       |
| `avatar_static`          | URL to the avatar static image (gif)                                               | no       |
| `header`                 | URL to the header image                                                            | no       |
| `header_static`          | URL to the header static image (gif)                                               | no       |
| `moved`                  | If the owner decided to switch accounts, new account is in this attribute          | yes      |

### Application

| Attribute                | Description             | Nullable |
| ------------------------ | ----------------------- | -------- |
| `name`                   | Name of the app         | no       |
| `website`                | Homepage URL of the app | yes      |

### Attachment

| Attribute                | Description                                                                       | Nullable |
| ------------------------ | --------------------------------------------------------------------------------- | -------- |
| `id`                     | ID of the attachment                                                              | no       |
| `type`                   | One of: "image", "video", "gifv", "unknown"                                       | no       |
| `url`                    | URL of the locally hosted version of the image                                    | no       |
| `remote_url`             | For remote images, the remote URL of the original image                           | yes      |
| `preview_url`            | URL of the preview image                                                          | no       |
| `text_url`               | Shorter URL for the image, for insertion into text (only present on local images) | yes      |
| `meta`                   | `small` and `original` containing: `width`, `height`, `size`, `aspect`            | yes      |
| `description`            | A description of the image for the visually impaired (maximum 420 characters), or `null` if none provided  | yes      |

> **Note**: When the type is "unknown", it is likely only `remote_url` is available and local `url` is missing

### Card

| Attribute                | Description                                | Nullable |
| ------------------------ | ------------------------------------------ | -------- |
| `url`                    | The url associated with the card           | no       |
| `title`                  | The title of the card                      | no       |
| `description`            | The card description                       | no       |
| `image`                  | The image associated with the card, if any | yes      |
| `type`                   | "link", "photo", "video", or "rich"        | no       |
| `author_name`            | OEmbed data                                | yes      |
| `author_url`             | OEmbed data                                | yes      |
| `provider_name`          | OEmbed data                                | yes      |
| `provider_url`           | OEmbed data                                | yes      |
| `html`                   | OEmbed data                                | yes      |
| `width`                  | OEmbed data                                | yes      |
| `height`                 | OEmbed data                                | yes      |

### Context

| Attribute                | Description                                                                         | Nullable |
| ------------------------ | ----------------------------------------------------------------------------------- | -------- |
| `ancestors`              | The ancestors of the status in the conversation, as a list of [Statuses](#status)   | no       |
| `descendants`            | The descendants of the status in the conversation, as a list of [Statuses](#status) | no       |

### Emoji

| Attribute                | Description                        | Nullable |
|--------------------------|------------------------------------|----------|
| `shortcode`              | The shortcode of the emoji         | no       |
| `static_url`             | URL to the emoji static image      | no       |
| `url`                    | URL to the emoji image             | no       |

### Error

The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure:

| Attribute                | Description                        | Nullable |
| ------------------------ | ---------------------------------- | -------- |
| `error`                  | A textual description of the error | no       |

### Instance

| Attribute                | Description                                                              | Nullable |
| ------------------------ | ------------------------------------------------------------------------ | -------- |
| `uri`                    | URI of the current instance                                              | no       |
| `title`                  | The instance's title                                                     | no       |
| `description`            | A description for the instance                                           | no       |
| `email`                  | An email address which can be used to contact the instance administrator | no       |
| `version`                | The Mastodon version used by instance.                                   | no       |
| `urls`                   | `streaming_api`                                                          | no       |

### Mention

| Attribute                | Description                                                           | Nullable |
| ------------------------ | --------------------------------------------------------------------- | -------- |
| `url`                    | URL of user's profile (can be remote)                                 | no       |
| `username`               | The username of the account                                           | no       |
| `acct`                   | Equals `username` for local users, includes `@domain` for remote ones | no       |
| `id`                     | Account ID                                                            | no       |

### Notification

| Attribute                | Description                                                           | Nullable |
| ------------------------ | --------------------------------------------------------------------- | -------- |
| `id`                     | The notification ID                                                   | no       |
| `type`                   | One of: "mention", "reblog", "favourite", "follow"                    | no       |
| `created_at`             | The time the notification was created                                 | no       |
| `account`                | The [Account](#account) sending the notification to the user          | no       |
| `status`                 | The [Status](#status) associated with the notification, if applicable | yes      |

### Relationship

| Attribute                | Description                                                  | Nullable |
| ------------------------ | ------------------------------------------------------------ | -------- |
| `id`                     | Target account id                                            | no       |
| `following`              | Whether the user is currently following the account          | no       |
| `followed_by`            | Whether the user is currently being followed by the account  | no       |
| `blocking`               | Whether the user is currently blocking the account           | no       |
| `muting`                 | Whether the user is currently muting the account             | no       |
| `muting_notifications`   | Whether the user is also muting notifications                | no       |
| `requested`              | Whether the user has requested to follow the account         | no       |
| `domain_blocking`        | Whether the user is currently blocking the accounts's domain | no       |

### Report

| Attribute                | Description                                | Nullable |
| ------------------------ | ------------------------------------------ | -------- |
| `id`                     | The ID of the report                       | no       |
| `action_taken`           | The action taken in response to the report | no       |

### Results

| Attribute                | Description                              | Nullable |
| ------------------------ | ---------------------------------------- | -------- |
| `accounts`               | An array of matched [Accounts](#account) | no      |
| `statuses`               | An array of matched [Statuses](#status)  | no      |
| `hashtags`               | An array of matched hashtags, as strings | no      |

### Status

| Attribute                | Description                                                                   | Nullable |
| ------------------------ | ----------------------------------------------------------------------------- | -------- |
| `id`                     | The ID of the status                                                          | no       |
| `uri`                    | A Fediverse-unique resource ID                                                | no       |
| `url`                    | URL to the status page (can be remote)                                        | no       |
| `account`                | The [Account](#account) which posted the status                               | no       |
| `in_reply_to_id`         | `null` or the ID of the status it replies to                                  | yes      |
| `in_reply_to_account_id` | `null` or the ID of the account it replies to                                 | yes      |
| `reblog`                 | `null` or the reblogged [Status](#status)                                     | yes      |
| `content`                | Body of the status; this will contain HTML (remote HTML already sanitized)    | no       |
| `created_at`             | The time the status was created                                               | no       |
| `emojis`                 | An array of [Emoji](#emoji)                                                   | yes      |
| `reblogs_count`          | The number of reblogs for the status                                          | no       |
| `favourites_count`       | The number of favourites for the status                                       | no       |
| `reblogged`              | Whether the authenticated user has reblogged the status                       | yes      |
| `favourited`             | Whether the authenticated user has favourited the status                      | yes      |
| `muted`                  | Whether the authenticated user has muted the conversation this status from    | yes      |
| `sensitive`              | Whether media attachments should be hidden by default                         | no       |
| `spoiler_text`           | If not empty, warning text that should be displayed before the actual content | no       |
| `visibility`             | One of: `public`, `unlisted`, `private`, `direct`                             | no       |
| `media_attachments`      | An array of [Attachments](#attachment)                                        | no       |
| `mentions`               | An array of [Mentions](#mention)                                              | no       |
| `tags`                   | An array of [Tags](#tag)                                                      | no       |
| `application`            | [Application](#application) from which the status was posted                  | yes      |
| `language`               | The detected language for the status, if detected                             | yes      |
| `pinned`                 | Whether this is the pinned status for the account that posted it              | yes      |

> **NOTE**: When `spoiler_text` is present, `sensitive` is true 

### Tag

| Attribute                | Description                                  | Nullable |
| ------------------------ | -------------------------------------------- | -------- |
| `name`                   | The hashtag, not including the preceding `#` | no       |
| `url`                    | The URL of the hashtag                       | no       |

### List

| Attribute | Description       | Nullable |
|-----------|-------------------|----------|
| `id`      | ID of the list    | no       |
| `title`   | Title of the list | no       |