> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/methods/accounts.md).

# accounts

## Account credentials

## Register an account

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts`

Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.\
\
**Returns:** Token\
**OAuth:** App token + `write:accounts`\
**Version:**\
2.7.0 - added\
3.0.0 - added `reason` parameter

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | Bearer \<app token> |

#### Request Body

| Name      | Type    | Description                                                                                                                                                                     |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| reason    | string  | Text that will be reviewed by moderators if registrations require manual approval.                                                                                              |
| username  | string  | The desired username for the account                                                                                                                                            |
| email     | string  | The email address to be used for login                                                                                                                                          |
| password  | string  | The password to be used for login                                                                                                                                               |
| agreement | boolean | Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE. |
| locale    | string  | The language of the confirmation email that will be sent                                                                                                                        |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="401 " %}

```
```

{% endtab %}
{% endtabs %}

## Verify account credentials

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/verify_credentials`

Test to make sure that the user token works. \
\
**Returns:** the user's own Account with Source\
**OAuth**: User token + `read:accounts`\
**Version history:**\
0.0.0 - added

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Note the extra source property, which is not visible on accounts other than your own. Also note that plain-text is used within source and HTML is used for their corresponding properties such as note and fields." %}

```javascript
{
  "id": "14715",
  "username": "trwnh",
  "acct": "trwnh",
  "display_name": "infinite love ⴳ",
  "locked": false,
  "bot": false,
  "created_at": "2016-11-24T10:02:12.085Z",
  "note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
  "url": "https://mastodon.social/@trwnh",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "followers_count": 821,
  "following_count": 178,
  "statuses_count": 33120,
  "last_status_at": "2019-11-24T15:49:42.251Z",
  "source": {
    "privacy": "public",
    "sensitive": false,
    "language": "",
    "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
    "fields": [
      {
        "name": "Website",
        "value": "https://trwnh.com",
        "verified_at": "2019-08-29T04:14:55.571+00:00"
      },
      {
        "name": "Sponsor",
        "value": "https://liberapay.com/at",
        "verified_at": "2019-11-15T10:06:15.557+00:00"
      },
      {
        "name": "Fan of:",
        "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
        "verified_at": null
      },
      {
        "name": "Main topics:",
        "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
        "verified_at": null
      }
    ],
    "follow_requests_count": 0
  },
  "emojis": [
    {
      "shortcode": "fatyoshi",
      "url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Website",
      "value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-08-29T04:14:55.571+00:00"
    },
    {
      "name": "Sponsor",
      "value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-15T10:06:15.557+00:00"
    },
    {
      "name": "Fan of:",
      "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&apos;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
      "verified_at": null
    },
    {
      "name": "Main topics:",
      "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i&apos;m just here to hang out and talk to cool people!",
      "verified_at": null
    }
  ]
}
```

{% endtab %}

{% tab title="401 Your credential verification will fail if the token is invalid or incorrect." %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="403 Your user account is currently disabled, missing a confirmed email address, or pending approval." %}
{% tabs %}
{% tab title="disabled" %}

```javascript
{
  "error": "Your login is currently disabled"
}
```

{% endtab %}

{% tab title="unconfirmed" %}

```javascript
{
  "error": "Your login is missing a confirmed e-mail address"
}
```

{% endtab %}

{% tab title="unapproved" %}

```javascript
{
  "error": "Your login is currently pending approval"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Update account credentials

<mark style="color:purple;">`PATCH`</mark> `https://mastodon.example/api/v1/accounts/update_credentials`

Update the user's display and preferences.\
\
**Returns:** the user's own Account with Source\
**OAuth:** User token + `write:accounts`\
**Version history:** \
1.1.1 - added\
2.3.0 - added `locked` parameter\
2.4.0 - added `source[privacy,sensitive]` parameters\
2.7.0 - added `discoverable` parameter<br>

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name               | Type    | Description                                                                                           |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------- |
| discoverable       | string  | Whether the account should be shown in the profile directory.                                         |
| bot                | boolean | Whether the account has a bot flag.                                                                   |
| display\_name      | string  | The display name to use for the profile.                                                              |
| note               | string  | The account bio.                                                                                      |
| avatar             | string  | Avatar image encoded using multipart/form-data                                                        |
| header             | string  | Header image encoded using multipart/form-data                                                        |
| locked             | boolean | Whether manual approval of follow requests is required.                                               |
| source\[privacy]   | string  | Default post privacy for authored statuses.                                                           |
| source\[sensitive] | boolean | Whether to mark authored statuses as sensitive by default.                                            |
| source\[language]  | string  | Default language to use for authored statuses. (ISO 6391)                                             |
| fields\_attributes | array   | Profile metadata `name` and `value`. (By default, max 4 fields and 255 characters per property/value) |

{% tabs %}
{% tab title="200 You should use accounts/verify\_credentials to first obtain plaintext representations from within the source parameter, then allow the user to edit these plaintext representations before submitting them through this API. The server will generate the corresponding HTML." %}

```javascript
{
  "id": "14715",
  "username": "trwnh",
  "acct": "trwnh",
  "display_name": "infinite love ⴳ",
  "locked": false,
  "bot": false,
  "created_at": "2016-11-24T10:02:12.085Z",
  "note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
  "url": "https://mastodon.social/@trwnh",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "followers_count": 834,
  "following_count": 182,
  "statuses_count": 33760,
  "last_status_at": "2019-12-01T00:12:08.731Z",
  "source": {
    "privacy": "public",
    "sensitive": false,
    "language": "",
    "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
    "fields": [
      {
        "name": "Website",
        "value": "https://trwnh.com",
        "verified_at": "2019-08-29T04:14:55.571+00:00"
      },
      {
        "name": "Sponsor",
        "value": "https://liberapay.com/at",
        "verified_at": "2019-11-15T10:06:15.557+00:00"
      },
      {
        "name": "Fan of:",
        "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
        "verified_at": null
      },
      {
        "name": "Main topics:",
        "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
        "verified_at": null
      }
    ],
    "follow_requests_count": 0
  },
  "emojis": [
    {
      "shortcode": "fatyoshi",
      "url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Website",
      "value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-08-29T04:14:55.571+00:00"
    },
    {
      "name": "Sponsor",
      "value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-15T10:06:15.557+00:00"
    },
    {
      "name": "Fan of:",
      "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&apos;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
      "verified_at": null
    },
    {
      "name": "Main topics:",
      "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i&apos;m just here to hang out and talk to cool people!",
      "verified_at": null
    }
  ]
}
```

{% endtab %}

{% tab title="401 " %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Retrieve information

## Account

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id`

View information about a profile.\
\
**Returns:** Account\
**OAuth:** Public\
**Version history:**\
0.0.0 - added\
2.4.0 - returns 410 if account is suspended

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

{% tabs %}
{% tab title="200 Account record will be returned. Note that acct of local users does not include the domain name." %}
{% tabs %}
{% tab title="Local user" %}

```javascript
{
  "id": "1",
  "username": "Gargron",
  "acct": "Gargron",
  "display_name": "Eugen",
  "locked": false,
  "bot": false,
  "created_at": "2016-03-16T14:34:26.392Z",
  "note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
  "url": "https://mastodon.social/@Gargron",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
  "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
  "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
  "followers_count": 318699,
  "following_count": 453,
  "statuses_count": 61013,
  "last_status_at": "2019-11-30T20:02:08.277Z",
  "emojis": [],
  "fields": [
    {
      "name": "Patreon",
      "value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
      "verified_at": null
    },
    {
      "name": "Homepage",
      "value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-07-15T18:29:57.191+00:00"
    }
  ]
}
```

{% endtab %}

{% tab title="Remote user" %}

```javascript
{
  "id": "23634",
  "username": "noiob",
  "acct": "noiob@awoo.space",
  "display_name": "shork",
  "locked": false,
  "bot": false,
  "created_at": "2017-02-08T02:00:53.274Z",
  "note": "<p>:ms_rainbow_flag:​ :ms_bisexual_flag:​ :ms_nonbinary_flag:​ <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span></a>.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span></a> ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span></a> ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span></a> ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span></a> and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span></a></span></p>",
  "url": "https://awoo.space/@noiob",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
  "header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
  "header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
  "followers_count": 553,
  "following_count": 405,
  "statuses_count": 28982,
  "last_status_at": "2019-12-01T00:39:57.264Z",
  "emojis": [
    {
      "shortcode": "ms_rainbow_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
      "visible_in_picker": true
    },
    {
      "shortcode": "ms_bisexual_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
      "visible_in_picker": true
    },
    {
      "shortcode": "ms_nonbinary_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Pronouns",
      "value": "they/them",
      "verified_at": null
    },
    {
      "name": "Alt",
      "value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span></a></span>",
      "verified_at": null
    },
    {
      "name": "Bots",
      "value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span></a></span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span></a></span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span></a></span>",
      "verified_at": null
    },
    {
      "name": "Website",
      "value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-23T20:25:47.907+00:00"
    }
  ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 If the instance is in whitelist mode and the Authorization header is missing or invalid" %}

```javascript
{
  "error": "This API requires an authenticated user"
}
```

{% endtab %}

{% tab title="404 Account does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account is suspended" %}

```markup
```

{% endtab %}
{% endtabs %}

## Statuses

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id/statuses`

Statuses posted to the given account.\
\
**Returns:** Array of Status\
**OAuth:** Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)\
**Version history:**\
0.0.0 - added\
2.6.0 - add min\_id\
2.7.0 - add exclude\_reblogs and allow unauthed use\
2.8.0 - add tagged parameter

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="401 Instance is in whitelist mode or running a version of Mastodon older than 2.7.0, and the Authorization header is invalid or missing" %}
{% tabs %}
{% tab title="whitelist" %}

```javascript
{
  "error": "This API requires an authenticated user"
}
```

{% endtab %}

{% tab title="pre-2.7.0" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Account is deleted or does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account is suspended" %}

```
```

{% endtab %}
{% endtabs %}

## Followers

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id/followers`

Accounts which follow the given account, if network is not hidden by the account owner.\
\
**Returns:** Array of Account\
**OAuth:** App token + `read:accounts`\
**Version history:** \
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Query Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| max\_id   | string |             |
| since\_id | string |             |
| limit     | number |             |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | Bearer \<app token> |

{% tabs %}
{% tab title="200 Sample output with limit=2. Because the ID of follow relationships is not generally used or provided with any API calls, an HTTP Link header is used instead to indicate next and previous pages. You will have to parse this header yourself to extract the paging URLs." %}

```javascript
Link: <https://mastodon.social/api/v1/accounts/14715/followers?limit=2&max_id=7486869>; rel="next", <https://mastodon.social/api/v1/accounts/14715/followers?limit=2&since_id=7489740>; rel="prev"

[
  {
    "id": "1020382",
    "username": "atul13061987",
    "acct": "atul13061987",
    "display_name": "",
    "locked": false,
    "bot": false,
    "created_at": "2019-12-04T07:17:02.745Z",
    "note": "<p></p>",
    "url": "https://mastodon.social/@atul13061987",
    "avatar": "https://mastodon.social/avatars/original/missing.png",
    "avatar_static": "https://mastodon.social/avatars/original/missing.png",
    "header": "https://mastodon.social/headers/original/missing.png",
    "header_static": "https://mastodon.social/headers/original/missing.png",
    "followers_count": 0,
    "following_count": 2,
    "statuses_count": 0,
    "last_status_at": null,
    "emojis": [],
    "fields": []
  },
  {
    "id": "1020381",
    "username": "linuxliner",
    "acct": "linuxliner",
    "display_name": "",
    "locked": false,
    "bot": false,
    "created_at": "2019-12-04T07:15:56.426Z",
    "note": "<p></p>",
    "url": "https://mastodon.social/@linuxliner",
    "avatar": "https://mastodon.social/avatars/original/missing.png",
    "avatar_static": "https://mastodon.social/avatars/original/missing.png",
    "header": "https://mastodon.social/headers/original/missing.png",
    "header_static": "https://mastodon.social/headers/original/missing.png",
    "followers_count": 0,
    "following_count": 2,
    "statuses_count": 0,
    "last_status_at": null,
    "emojis": [],
    "fields": []
  }
]
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header, or instance is in whitelist mode and your token is not authorized with a user" %}
{% tabs %}
{% tab title="header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="whitelist" %}

```javascript
{
  "error": "This API requires an authenticated user"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Account is deleted or does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account is suspended" %}

```
```

{% endtab %}
{% endtabs %}

## Following

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id/following`

Accounts which the given account is following, if network is not hidden by the account owner.\
\
**Returns:** Array of Account\
**OAuth:** App token + `read:accounts`\
**Version history:** \
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Query Parameters

| Name      | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| max\_id   | string | **Internal parameter.** Use HTTP `Link` header for pagination. |
| since\_id | string | **Internal parameter.** Use HTTP `Link` header for pagination. |
| limit     | string | Maximum number of results to return. Defaults to 40.           |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | Bearer \<app token> |

{% tabs %}
{% tab title="200 Sample output with limit=2. Because the ID of follow relationships is not generally used or provided with any API calls, an HTTP Link header is used instead to indicate next and previous pages. You will have to parse this header yourself to extract the paging URLs." %}

```javascript
Link: <https://mastodon.social/api/v1/accounts/1/followers?limit=2&max_id=7628164>; rel="next", <https://mastodon.social/api/v1/accounts/1/followers?limit=2&since_id=7628165>; rel="prev"

[
  {
    "id": "963410",
    "username": "gautambhatia",
    "acct": "gautambhatia",
    "display_name": "Gautam Bhatia",
    "locked": false,
    "bot": false,
    "created_at": "2019-11-07T13:06:57.442Z",
    "note": "<p>SF reader, editor, and writer.</p>",
    "url": "https://mastodon.social/@gautambhatia",
    "avatar": "https://files.mastodon.social/accounts/avatars/000/963/410/original/d8e0fd5cefcf9687.jpg",
    "avatar_static": "https://files.mastodon.social/accounts/avatars/000/963/410/original/d8e0fd5cefcf9687.jpg",
    "header": "https://mastodon.social/headers/original/missing.png",
    "header_static": "https://mastodon.social/headers/original/missing.png",
    "followers_count": 1900,
    "following_count": 52,
    "statuses_count": 183,
    "last_status_at": "2019-12-02T17:52:39.463Z",
    "emojis": [],
    "fields": []
  },
  {
    "id": "1007400",
    "username": "seafrog",
    "acct": "seafrog@glitterkitten.co.uk",
    "display_name": "🐓🦃 Heck Partridge 🤠 🦆",
    "locked": false,
    "bot": false,
    "created_at": "2019-11-19T18:46:49.977Z",
    "note": "<p>hi im elise!! this is scribblefrog's new account</p><p>she/her, 27</p>",
    "url": "https://glitterkitten.co.uk/@seafrog",
    "avatar": "https://files.mastodon.social/accounts/avatars/001/007/400/original/306cd22c1b118693.png",
    "avatar_static": "https://files.mastodon.social/accounts/avatars/001/007/400/original/306cd22c1b118693.png",
    "header": "https://files.mastodon.social/accounts/headers/001/007/400/original/fd9728559f7265f5.jpeg",
    "header_static": "https://files.mastodon.social/accounts/headers/001/007/400/original/fd9728559f7265f5.jpeg",
    "followers_count": 168,
    "following_count": 223,
    "statuses_count": 944,
    "last_status_at": "2019-12-04T00:44:08.603Z",
    "emojis": [],
    "fields": [
      {
        "name": "gotdamb",
        "value": "frog",
        "verified_at": null
      },
      {
        "name": "whomst lov",
        "value": "the oceane",
        "verified_at": null
      }
    ]
  }
]
```

{% endtab %}

{% tab title="401 " %}
{% tabs %}
{% tab title="header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="whitelist" %}

```
{
  "error": "This API requires an authenticated user"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 Account is deleted or does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account is suspended" %}

```
```

{% endtab %}
{% endtabs %}

## Lists containing this account

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id/lists`

User lists that you have added this account to.\
\
**Returns:** Array of List\
**OAuth:** User token + `read:lists`\
**Version history:**\
2.1.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 If the account is part of any lists, those entities will be returned. If the account is not part of any of your lists, then an empty array will be returned." %}
{% tabs %}
{% tab title="part of lists" %}

```javascript
[
  {
    "id": "13694",
    "title": "dev"
  }
]
```

{% endtab %}

{% tab title="not in any lists" %}

```javascript
[]
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="404 Account with given id does not exist or is deleted" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account with given id is suspended" %}

```
```

{% endtab %}
{% endtabs %}

## Identity proofs

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/:id/identity_proofs`

**Returns:** Array of IdentityProof\
**OAuth:** User token \
**Version history:**\
2.8.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "provider": "Keybase",
    "provider_username": "gargron",
    "updated_at": "2019-07-21T20:14:39.596Z",
    "proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f",
    "profile_url": "https://keybase.io/gargron"
  }
]
```

{% endtab %}

{% tab title="404 Account with given id is deleted or does not exist" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}

{% tab title="410 Account with given id is suspended" %}

```
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
  "error": "This method requires an authenticated user"
}
```

{% endtab %}
{% endtabs %}

## Perform actions on an account

## Follow

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/follow`

Follow the given account.\
\
**Returns:** Relationship\
**OAuth:** User token + `write:follows` or `follow`\
**Version history:**\
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name    | Type    | Description                                                        |
| ------- | ------- | ------------------------------------------------------------------ |
| reblogs | boolean | Receive this account's reblogs in home timeline? Defaults to true. |

{% tabs %}
{% tab title="200 Successfully followed, or account was already followed" %}

```javascript
{
  "id": "3",
  "following": true,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="403 Trying to follow someone that you block or that blocks you" %}

```javascript
{
  "error": "This action is not allowed"
}
```

{% endtab %}
{% endtabs %}

## Unfollow

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/unfollow`

Unfollow the given account.\
\
**Returns:** Relationship\
**OAuth:** User token + `write:follows` or `follow`\
**Version history:**\
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully unfollowed, or account was already not followed" %}

```javascript
{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Block

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/block`

Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)\
\
**Returns:** Relationship\
**OAuth:** User token + `write:blocks` or `follow`\
**Version history:** \
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully blocked, or account was already blocked" %}

```javascript
{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": true,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Unblock

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/unblock`

Unblock the given account.\
\
**Returns:** Relationship\
**OAuth:** User token + `write:blocks` or `follow`\
**Version history:**\
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully unblocked, or account was already not blocked" %}

```javascript
{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Mute

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/mute`

Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).\
\
**Returns:** Relationship\
**OAuth:** User token + `write:mutes` or `follow`\
**Version history:** \
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name          | Type    | Description                                                   |
| ------------- | ------- | ------------------------------------------------------------- |
| notifications | boolean | Mute notifications in addition to statuses? Defaults to true. |

{% tabs %}
{% tab title="200 Successfully muted, or account was already muted. Note that you can call this API method again with notifications=false to update the relationship so that only statuses are muted." %}

```javascript
{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": true,
  "muting_notifications": true,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Unmute

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/unmute`

Unmute the given account.\
\
**Returns:** Relationship\
**OAuth:** User token + `write:mutes` or `follow`\
**Version history:** \
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully unmuted, or account was already unmuted" %}

```javascript
{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Feature on profile

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/pin`

Add the given account to the user's featured profiles. (Featured profiles are currently shown on the user's own public profile.)\
\
**Returns:** Relationship\
**OAuth:** User token + `write:accounts`\
**Version history:**\
2.5.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully endorsed." %}

```javascript
{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": true
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="403 Token is not authorized with a valid user or is missing a required scope" %}

```javascript
{
  "error": "This action is outside the authorized scopes"
}
```

{% endtab %}

{% tab title="422 You are not following this account" %}

```javascript
{
  "error": "Validation failed: You must be already following the person you want to endorse"
}
```

{% endtab %}

{% tab title="500 Account already endorsed" %}

```
```

{% endtab %}
{% endtabs %}

## Unfeature on profile

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/accounts/:id/unpin`

Remove the given account from the user's featured profiles.\
\
**Returns:** Relationship\
**OAuth:** User + `write:accounts`\
**Version history:** \
2.5.0 - added

#### Path Parameters

| Name | Type   | Description                           |
| ---- | ------ | ------------------------------------- |
| :id  | string | The id of the account in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Successfully unendorsed, or account was already not endorsed" %}

```javascript
{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}
```

{% endtab %}

{% tab title="401 " %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="422 " %}

```
```

{% endtab %}
{% endtabs %}

## General account actions

## Check relationships to other accounts

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/relationships`

Find out whether a given account is followed, blocked, muted, etc.\
\
**Returns:** Array of Relationship\
**OAuth:** User token + `read:follows`\
**Version history:** \
0.0.0 - added

#### Query Parameters

| Name  | Type  | Description                   |
| ----- | ----- | ----------------------------- |
| id\[] | array | Array of account IDs to check |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Sample call with id\[]=1\&id\[]=2" %}

```javascript
[
  {
    "id": "1",
    "following": true,
    "showing_reblogs": true,
    "followed_by": true,
    "blocking": false,
    "blocked_by": false,
    "muting": false,
    "muting_notifications": false,
    "requested": false,
    "domain_blocking": false,
    "endorsed": false
  },
  {
    "id": "2",
    "following": false,
    "showing_reblogs": false,
    "followed_by": false,
    "blocking": false,
    "blocked_by": false,
    "muting": false,
    "muting_notifications": false,
    "requested": false,
    "domain_blocking": false,
    "endorsed": false
  }
]
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

```javascript
{
  "error": "The access token is invalid"
}
```

{% endtab %}

{% tab title="422 Token does not have an authorized user" %}

```javascript
{
  "error": "This method requires an authenticated user"
}
```

{% endtab %}
{% endtabs %}

## Search for matching accounts

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/accounts/search`

Search for matching accounts by username or display name.\
\
**Returns:** Array of Account\
**OAuth:** User token + `read:accounts`\
**Version history:** \
0.0.0 - added

#### Query Parameters

| Name      | Type   | Description                                                                         |
| --------- | ------ | ----------------------------------------------------------------------------------- |
| q         | string | What to search for                                                                  |
| limit     | string | Maximum number of results. Defaults to 40.                                          |
| resolve   | string | Attempt WebFinger lookup. Defaults to false. Use this when `q` is an exact address. |
| following | string | Only who the user is following. Defaults to false.                                  |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Accounts matching "trwnh" in username or display name" %}

```javascript
[
  {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    ...
  },
  {
    "id": "418714",
    "username": "trwnh",
    "acct": "trwnh@pixelfed.social",
    "display_name": "Abdullah Tarawneh",
    ...
  },
  {
    "id": "419674",
    "username": "trwnh",
    "acct": "trwnh@write.as",
    "display_name": "trwnh",
    ...
  },
  ...
]
```

{% endtab %}

{% tab title="503 resolve=true, but the domain part of the user\@domain address is not a currently live website" %}

```javascript
{
  "error": "Remote data could not be fetched"
}
```

{% endtab %}
{% endtabs %}