accounts

Methods concerning user accounts and related information.

Account credentials

post
Register an account

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 history:
2.7.0 - added
3.0.0 - added reason parameter

Request

Headers

Authorization

required

string

Bearer <app token>

Form Data Parameters

reason

optional

string

Text that will be reviewed by moderators if registrations require manual approval.

username

required

string

The desired username for the account

required

string

The email address to be used for login

password

required

string

The password to be used for login

agreement

required

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

required

string

The language of the confirmation email that will be sent

Response

200: Success

401: Unauthorized

get
Verify account credentials

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

Request

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

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.

{
  "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: [email protected]<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: [email protected]\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
    }
  ]
}

401: Unauthorized

Your credential verification will fail if the token is invalid or incorrect.

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

403: Forbidden

Your user account is currently disabled, missing a confirmed email address, or pending approval.

disabled

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

unconfirmed

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

unapproved

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

patch
Update account credentials

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

Request

Headers

Authorization

required

string

Bearer <user token>

Form Data Parameters

discoverable

optional

string

Whether the account should be shown in the profile directory.

bot

optional

boolean

Whether the account has a bot flag.

display_name

optional

string

The display name to use for the profile.

note

optional

string

The account bio.

avatar

optional

string

Avatar image encoded using multipart/form-data

header

optional

string

Header image encoded using multipart/form-data

locked

optional

boolean

Whether manual approval of follow requests is required.

source[privacy]

optional

string

Default post privacy for authored statuses.

source[sensitive]

optional

boolean

Whether to mark authored statuses as sensitive by default.

source[language]

optional

string

Default language to use for authored statuses. (ISO 6391)

fields_attributes

optional

array

Profile metadata name and value. (By default, max 4 fields and 255 characters per property/value)

Response

200: Success

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.

{
  "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: [email protected]<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: [email protected]\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
    }
  ]
}

401: Unauthorized

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

Retrieve information

get
Account

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
3.3.0 - returns an Account with suspended: true instead of 410

Request

Path Parameters

:id

required

string

The id of the account in the database

Response

200: Success

Account record will be returned. Note that acct of local users does not include the domain name.

Local user

{
  "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"
    }
  ]
}

Remote user

{
  "id": "23634",
  "username": "noiob",
  "acct": "[email protected]",
  "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"
    }
  ]
}

Suspended user

{
  "id": "14",
  "username": "stigatle",
  "acct": "[email protected]",
  "display_name": "",
  "locked": false,
  "bot": false,
  "discoverable": false,
  "group": false,
  "created_at": "2016-03-18T10:04:51.700Z",
  "note": "",
  "url": "https://quitter.no/stigatle",
  "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": 0,
  "statuses_count": 0,
  "last_status_at": null,
  "suspended": true,
  "emojis": [],
  "fields": []
}

401: Unauthorized

If the instance is in whitelist mode and the Authorization header is missing or invalid

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

404: Not Found

Account does not exist

{
  "error": "Record not found"
}

410: Gone

Account is suspended

get
Statuses

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

optional

string

Bearer <user token>

Response

200: Success

401: Unauthorized

Instance is in whitelist mode or running a version of Mastodon older than 2.7.0, and the Authorization header is invalid or missing

whitelist

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

pre-2.7.0

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

404: Not Found

Account is deleted or does not exist

{
  "error": "Record not found"
}

410: Gone

Account is suspended

get
Followers

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <app token>

Query Parameters

max_id

optional

string

since_id

optional

string

limit

optional

number

Response

200: Success

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.

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": []
  }
]

401: Unauthorized

Invalid or missing Authorization header, or instance is in whitelist mode and your token is not authorized with a user

header

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

whitelist

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

404: Not Found

Account is deleted or does not exist

{
  "error": "Record not found"
}

410: Gone

Account is suspended

get
Following

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <app token>

Query Parameters

max_id

optional

string

Internal parameter. Use HTTP Link header for pagination.

since_id

optional

string

Internal parameter. Use HTTP Link header for pagination.

limit

optional

string

Maximum number of results to return. Defaults to 40.

Response

200: Success

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": "[email protected]",
    "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
      }
    ]
  }
]

401: Unauthorized

header

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

whitelist

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

404: Not Found

Account is deleted or does not exist

{
  "error": "Record not found"
}

410: Gone

Account is suspended

get
Featured tags

https://mastodon.example/api/v1/accounts/:id/featured_tags

Tags featured by this account.

Returns: Array of FeaturedTag
OAuth: User token + read:accounts
Version history:
3.3.0 - added

Request

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

[
  {
    "id": "627",
    "name": "nowplaying",
    "statuses_count": 36,
    "last_status_at": "2019-11-15T07:14:43.524Z"
  }
]

401: Unauthorized

Invalid or missing Authorization header

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

get
Lists containing this account

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

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.

part of lists

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

not in any lists

[]

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Account with given id does not exist or is deleted

{
  "error": "Record not found"
}

410: Gone

Account with given id is suspended

get
Identity proofs

https://mastodon.example/api/v1/accounts/:id/identity_proofs

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Response

200: Success

[
  {
    "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"
  }
]

404: Not Found

Account with given id is deleted or does not exist

{
  "error": "Record not found"
}

410: Gone

Account with given id is suspended

422: Unprocessable Entity

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

Perform actions on an account

post
Follow

https://mastodon.example/api/v1/accounts/:id/follow

Follow the given account. Can also be used to update whether to show reblogs or enable notifications.

Returns: Relationship
OAuth: User token + write:follows or follow
Version history:
0.0.0 - added
3.3.0 - added notify

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Form Data Parameters

reblogs

optional

boolean

Receive this account's reblogs in home timeline? Defaults to true.

notify

optional

boolean

Receive notifications when this account posts a status? Defaults to false.

Response

200: Success

Successfully followed, or account was already followed

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

403: Forbidden

Trying to follow someone that you block or that blocks you

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

post
Unfollow

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully unfollowed, or account was already not followed

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

401: Unauthorized

Invalid or missing Authorization header

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

post
Block

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully blocked, or account was already blocked

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

401: Unauthorized

Invalid or missing Authorization header

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

post
Unblock

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully unblocked, or account was already not blocked

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

401: Unauthorized

Invalid or missing Authorization header

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

post
Mute

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Form Data Parameters

notifications

optional

boolean

Mute notifications in addition to statuses? Defaults to true.

duration

optional

number

How long the mute should last, in seconds. Defaults to 0 (indefinite).

Response

200: Success

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.

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

401: Unauthorized

Invalid or missing Authorization header

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

post
Unmute

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully unmuted, or account was already unmuted

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

401: Unauthorized

Invalid or missing Authorization header

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

post
Feature on profile

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully endorsed.

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

401: Unauthorized

Invalid or missing Authorization header

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

403: Forbidden

Token is not authorized with a valid user or is missing a required scope

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

422: Unprocessable Entity

You are not following this account

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

500:

Account already endorsed

post
Unfeature on profile

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

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Successfully unendorsed, or account was already not endorsed

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

401: Unauthorized

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

422: Unprocessable Entity

post
User note

https://mastodon.example/api/v1/accounts/:id/note

Sets a private note on a user.

Returns: Relationship
OAuth: User + write:accounts
Version history:
3.2.0 - added

Request

Path Parameters

:id

required

string

The id of the account in the database

Headers

Authorization

required

string

Bearer <user token>

Form Data Parameters

comment

optional

string

The comment to be set on that user. Provide an empty string or leave out this parameter to clear the currently set note.

Response

200: Success

Successfully updated user note

{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false,
  "note": "this is a comment"
}

401: Unauthorized

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

422: Unprocessable Entity

General account actions

get
Check relationships to other accounts

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

Request

Headers

Authorization

required

string

Bearer <user token>

Query Parameters

id[]

required

array

Array of account IDs to check

Response

200: Success

Sample call with id[]=1&id[]=2

[
  {
    "id": "1",
    "following": true,
    "showing_reblogs": true,
    "notifying": false,
    "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,
    "notifying": false,
    "followed_by": false,
    "blocking": false,
    "blocked_by": false,
    "muting": false,
    "muting_notifications": false,
    "requested": false,
    "domain_blocking": false,
    "endorsed": false
  }
]

401: Unauthorized

Invalid or missing Authorization header

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

422: Unprocessable Entity

Token does not have an authorized user

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

get
Search for matching accounts

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

Request

Headers

Authorization

required

string

Bearer <user token>

Query Parameters

required

string

What to search for

limit

optional

string

Maximum number of results. Defaults to 40.

resolve

optional

string

Attempt WebFinger lookup. Defaults to false. Use this when q is an exact address.

following

optional

string

Only who the user is following. Defaults to false.

Response

200: Success

Accounts matching “trwnh” in username or display name

[
  {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    ...
  },
  {
    "id": "418714",
    "username": "trwnh",
    "acct": "[email protected]",
    "display_name": "Abdullah Tarawneh",
    ...
  },
  {
    "id": "419674",
    "username": "trwnh",
    "acct": "[email protected]",
    "display_name": "trwnh",
    ...
  },
  ...
]

503:

resolve=true, but the domain part of the user@domain address is not a currently live website

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

Last updated December 27, 2020 · Improve this page

accounts

Account credentials

postRegister an account

Request

Headers

Form Data Parameters

Response

200: Success

401: Unauthorized

getVerify account credentials

Request

Headers

Response

200: Success

401: Unauthorized

403: Forbidden

disabled

unconfirmed

unapproved

patchUpdate account credentials

Request

Headers

Form Data Parameters

Response

200: Success

401: Unauthorized

Retrieve information

getAccount

Request

Path Parameters

Response

200: Success

Local user

Remote user

Suspended user

401: Unauthorized

404: Not Found

410: Gone

getStatuses

Request

Path Parameters

Headers

Response

200: Success

401: Unauthorized

whitelist

pre-2.7.0

404: Not Found

410: Gone

getFollowers

Request

Path Parameters

Headers

Query Parameters

Response

200: Success

401: Unauthorized

header

whitelist

404: Not Found

410: Gone

getFollowing

Request

Path Parameters

Headers

Query Parameters

Response

200: Success

401: Unauthorized

header

whitelist

404: Not Found

410: Gone

getFeatured tags

Request

Headers

Response

200: Success

401: Unauthorized

getLists containing this account

post
Register an account

get
Verify account credentials

patch
Update account credentials

get
Account

get
Statuses

get
Followers

get
Following

get
Featured tags

get
Lists containing this account

get
Identity proofs

post
Follow

post
Unfollow

post
Block

post
Unblock

post
Mute

post
Unmute

post
Feature on profile