statuses

Publish, interact, and view information about statuses.

post
Publish new status

https://mastodon.example/api/v1/statuses

Post a new status.

Returns: Status. When scheduled_at is present, ScheduledStatus is returned instead.
OAuth: User + write:statuses
Version history:
0.0.0 - added
2.7.0 - scheduled_at added
2.8.0 - poll added

Request

Headers

Idempotency-Key

optional

string

Prevent duplicate submissions of the same status. Idempotency keys are stored for up to 1 hour, and can be any arbitrary string. Consider using a hash or UUID generated client-side.

Authorization

required

string

Bearer <user token>

Form Data Parameters

status

required

string

Text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided.

media_ids[]

required

array

Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used.

poll[options][]

required

array

Array of possible answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided.

poll[expires_in]

required

number

Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided.

poll[multiple]

optional

boolean

Allow multiple choices?

poll[hide_totals]

optional

boolean

Hide vote counts until the poll ends?

in_reply_to_id

optional

string

ID of the status being replied to, if status is a reply

sensitive

optional

boolean

Mark status and attached media as sensitive?

spoiler_text

optional

string

Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.

visibility

optional

string

Visibility of the posted status. Enumerable oneOf public, unlisted, private, direct.

scheduled_at

optional

string

ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.

language

optional

string

ISO 639 language code for this status.

Response

200: Success

Status will be posted with chosen parameters. If scheduled_at is provided, then a ScheduledStatus will be returned instead.

status

{
  "id": "103254962155278888",
  "created_at": "2019-12-05T11:34:47.196Z",
  ...
  "content": "<p>test content</p>",
  ...
  "application": {
    "name": "test app",
    "website": null
  },
  ...
}

scheduled_at ScheduledStatus

{
  "id": "3221",
  "scheduled_at": "2019-12-05T12:33:01.000Z",
  "params": {
    "text": "test content",
    "media_ids": null,
    "sensitive": null,
    "spoiler_text": null,
    "visibility": null,
    "scheduled_at": null,
    "poll": null,
    "idempotency": null,
    "in_reply_to_id": null,
    "application_id": 596551
  },
  "media_attachments": []
}

get
View specific status

https://mastodon.example/api/v1/statuses/:id

View information about a status.

Returns: Status
OAuth: Public for public statuses, user token + read:statuses for private statuses
Version history:
0.0.0 - added
2.7.0 - public statuses no longer require token

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

optional

string

Bearer <user token>

Response

200: Success

{
  "id": "1",
  "created_at": "2016-03-16T14:44:31.580Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/Gargron/statuses/1",
  "url": "https://mastodon.social/@Gargron/1",
  "replies_count": 7,
  "reblogs_count": 98,
  "favourites_count": 112,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "content": "<p>Hello world</p>",
  "reblog": null,
  "application": null,
  "account": {
    "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": 320472,
    "following_count": 453,
    "statuses_count": 61163,
    "last_status_at": "2019-12-05T03:03:02.595Z",
    "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"
      }
    ]
  },
  "media_attachments": [],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": null
}

401: Unauthorized

instance is in whitelist mode

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

404: Not Found

Status does not exist, is deleted, or is private.

{
  "error": "Record not found"
}

delete
Delete status

https://mastodon.example/api/v1/statuses/:id

Delete one of your own statuses.

Returns: Status with source text and media_attachments or poll
OAuth: User token + write:statuses
Version history:
0.0.0 - added
2.9.0 - return source properties, for use with delete and redraft

Request

Path Parameters

:id

required

string

Local ID of a status in the database. Must be owned by authenticated account.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Note the special properties text and media_attachments or poll which may be used to repost the status, e.g. in case of delete-and-redraft functionality. With POST /api/v1/statuses, use text as the value for status parameter, media_attachments[n]["id"] for the media_ids array parameter, and poll properties with the corresponding parameters (e.g. poll[multiple] and poll[options], with a new poll[expires_in] and poll[hide_totals] per user input.

with media

{
  "id": "103254193998341330",
  "created_at": "2019-12-05T08:19:26.052Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/trwnh/statuses/103254193998341330",
  "url": "https://mastodon.social/@trwnh/103254193998341330",
  "replies_count": 0,
  "reblogs_count": 0,
  "favourites_count": 0,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  "text": "test",
  "reblog": null,
  "application": {
    "name": "Web",
    "website": null
  },
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    ...
  },
  "media_attachments": [
    {
      "id": "22345792",
      "type": "image",
      "url": "https://files.mastodon.social/media_attachments/files/022/345/792/original/57859aede991da25.jpeg",
      "preview_url": "https://files.mastodon.social/media_attachments/files/022/345/792/small/57859aede991da25.jpeg",
      "remote_url": null,
      "text_url": "https://mastodon.social/media/2N4uvkuUtPVrkZGysms",
      "meta": {
        "original": {
          "width": 640,
          "height": 480,
          "size": "640x480",
          "aspect": 1.3333333333333333
        },
        "small": {
          "width": 461,
          "height": 346,
          "size": "461x346",
          "aspect": 1.3323699421965318
        },
        "focus": {
          "x": -0.27,
          "y": 0.51
        }
      },
      "description": "test media description",
      "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
    }
  ],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": null
}

with poll

{
  "id": "103254222827484720",
  "created_at": "2019-12-05T08:26:45.958Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/trwnh/statuses/103254222827484720",
  "url": "https://mastodon.social/@trwnh/103254222827484720",
  "replies_count": 0,
  "reblogs_count": 0,
  "favourites_count": 0,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  "text": "test",
  "reblog": null,
  "application": {
    "name": "Web",
    "website": null
  },
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    ...
  },
  "media_attachments": [],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": {
    "id": "34858",
    "expires_at": "2019-12-06T08:26:45.945Z",
    "expired": false,
    "multiple": false,
    "votes_count": 1,
    "voters_count": 1,
    "voted": true,
    "own_votes": [],
    "options": [
      {
        "title": "test 1",
        "votes_count": 1
      },
      {
        "title": "test 2",
        "votes_count": 0
      }
    ],
    "emojis": []
  }
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status already deleted, does not exist, or is not owned by you

{
  "error": "Record not found"
}

get
Parent and child statuses

https://mastodon.example/api/v1/statuses/:id/context

View statuses above and below this status in the thread.

Returns: Context
OAuth: Public for public statuses. User token + read:statuses for private statuses.
Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

optional

string

Bearer <user token>

Response

200: Success

{
  "ancestors": [
    {
      "id": "103188938570975982",
      "created_at": "2019-11-23T19:44:00.124Z",
      "in_reply_to_id": null,
      "in_reply_to_account_id": null,
      ...
    },
    {
      "id": "103188971072973252",
      "created_at": "2019-11-23T19:52:23.398Z",
      "in_reply_to_id": "103188938570975982",
      "in_reply_to_account_id": "634458",
      ...
    },
    {
      "id": "103188982235527758",
      "created_at": "2019-11-23T19:55:08.208Z",
      "in_reply_to_id": "103188971072973252",
      "in_reply_to_account_id": "14715",
      ...
    }
  ],
  "descendants": [
    {
      "id": "103189026958574542",
      "created_at": "2019-11-23T20:06:36.011Z",
      "in_reply_to_id": "103189005915505698",
      "in_reply_to_account_id": "634458",
      ...
    }
  ]
}

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

get
Boosted by

https://mastodon.example/api/v1/statuses/:id/reblogged_by

View who boosted a given status.

Returns: Array of Account
OAuth: Public Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Response

200: Success

[
  {
    "id": "711345",
    "username": "Norman_Doors",
    "acct": "Norman_Doors@witches.live",
    ...
  },
  ...
]

404: Not Found

Status does not exist, is deleted, or is private.

{
  "error": "Record not found"
}

get
Favourited by

https://mastodon.example/api/v1/statuses/:id/favourited_by

View who favourited a given status.

Returns: Array of Account
OAuth: Public
Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Response

200: Success

[
  {
    "id": "828600",
    "username": "fructose_dealer",
    "acct": "fructose_dealer@radical.town",
    ...
  },
  ...
]

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

post
Favourite

https://mastodon.example/api/v1/statuses/:id/favourite

Add a status to your favourites list.

Returns: Status
OAuth: User token + write:favourites
Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status favourited or was already favourited

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": true,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

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

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

post
Undo favourite

https://mastodon.example/api/v1/statuses/:id/unfavourite

Remove a status from your favourites list.

Returns: Status
OAuth: User token + write:favourites
Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status unfavourited or was already not favourited

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

post
Boost

https://mastodon.example/api/v1/statuses/:id/reblog

Reshare a status.

Returns: Status
OAuth: User token + write:statuses
Version history:
0.0.0 - added
2.8.0 - add visibility parameter

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Form Data Parameters

visibility

optional

string

any visibility except limited or direct (i.e. public, unlisted, private). Defaults to public. Currently unused in UI.

Response

200: Success

Status has been reblogged. Note that the top-level id has changed. The id of the boosted status is now inside the reblog property. The top-level id is the id of the reblog itself. Also note that reblogs cannot be pinned.

{
  "id": "103254401326800919",
  "created_at": "2019-12-05T09:12:09.625Z",
  ...
  "favourited": false,
  "reblogged": true,
  "muted": false,
  "bookmarked": false,
  ...
  "reblog": {
    "id": "99734435964706331",
    "created_at": "2018-03-23T17:38:40.700Z",
    ...
    "favourited": false,
    "reblogged": true,
    "muted": false,
    "bookmarked": false,
    "pinned": false,
    ...
  },
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

post
Undo boost

https://mastodon.example/api/v1/statuses/:id/unreblog

Undo a reshare of a status.

Returns: Status
OAuth: User token + write:statuses
Version history:
0.0.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status no longer reblogged

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing authorization header

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

404: Not Found

Status deleted, does not exist, or no reblog exists

{
 "error":  "Record not found"
}

post
Bookmark

https://mastodon.example/api/v1/statuses/:id/bookmark

Privately bookmark a status.

Returns: Status
OAuth: User token + write:bookmarks
Version history:
3.1.0 - added

Request

Path Parameters

:id

required

string

ID of the status in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status bookmarked

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": true,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

{
  "error": "Record not found"
}

post
Undo bookmark

https://mastodon.example/api/v1/statuses/:id/unbookmark

Remove a status from your private bookmarks.

Returns: Status
OAuth: User token + write:bookmarks
Version history:
3.1.0 - added

Request

Path Parameters

required

string

ID of the status in the database

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status does not exist, is deleted, is private, or was already not bookmarked

{
  "error": "Record not found"
}

post
Mute conversation

https://mastodon.example/api/v1/statuses/:id/mute

Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.

Returns: Status
OAuth: User token + write:mutes
Version history:
1.4.2 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status’s conversation muted, or was already muted

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": true,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

{
  "error": "Record not found"
}

post
Unmute conversation

https://mastodon.example/api/v1/statuses/:id/unmute

Start receiving notifications again for the thread that this status is part of.

Returns: Status
OAuth: User token + write:mutes
Version history:
1.4.2 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status’s conversation unmuted, or was already unmuted

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

{
  "error": "Record not found"
}

post
Pin to profile

https://mastodon.example/api/v1/statuses/:id/pin

Feature one of your own public statuses at the top of your profile.

Returns: Status
OAuth: User token + write:accounts
Version history:
1.6.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database. The status should be public and authored by the authorized account.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status pinned. Note the status is not a reblog and its authoring account is your own.

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": true,
  ...
  "reblog": null,
  ...
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    ...
  },
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status does not exist, is deleted, or you are not authorized to see it.

{
  "error": "Record not found"
}

422: Unprocessable Entity

Status is not owned by you, or is not public. You cannot pin one of your private statuses because private statuses cannot be fetched from remote sites, and must be delivered.

Not yours

{
  "error": "Validation failed: Someone else's toot cannot be pinned"
}

Private

{
  "error": "Validation failed: Non-public toot cannot be pinned"
}

post
Unpin to profile

https://mastodon.example/api/v1/statuses/:id/unpin

Unfeature a status from the top of your profile.

Returns: Status
OAuth: User token + write:accounts
Version history:
1.6.0 - added

Request

Path Parameters

:id

required

string

Local ID of a status in the database.

Headers

Authorization

required

string

Bearer <user token>

Response

200: Success

Status unpinned, or was already not pinned

{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  ...
  "reblog": null,
  ...
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    ...
  },
  ...
}

401: Unauthorized

Invalid or missing Authorization header

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

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

Deprecated methods

get
Preview card

https://mastodon.example/api/v1/statuses/:id/card

Returns: Card
OAuth: Public
Version history:
0.0.0 - added
2.6.0 - deprecated in favor of card property inlined on Status entity
3.0.0 - removed

Request

Path Parameters

:id

required

string

ID of the status in the database

Response

200: Success

{
  "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y",
  "title": "♪ Brand New Friend (Christmas Song!)",
  "description": "",
  "type": "video",
  "author_name": "YOGSCAST Lewis & Simon",
  "author_url": "https://www.youtube.com/user/BlueXephos",
  "provider_name": "YouTube",
  "provider_url": "https://www.youtube.com/",
  "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/OMv_EPMED8Y?feature=oembed\" frameborder=\"0\" allowfullscreen=\"\"></iframe>",
  "width": 480,
  "height": 270,
  "image": "https://files.mastodon.social/preview_cards/images/014/179/145/original/9cf4b7cf5567b569.jpeg",
  "embed_url": ""
}

404: Not Found

Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

Last updated December 27, 2020 · Improve this page

statuses

post Publish new status

Request

Headers

Form Data Parameters

Response

200: Success

status

scheduled_at ScheduledStatus

get View specific status

Request

Path Parameters

Headers

Response

200: Success

401: Unauthorized

404: Not Found

delete Delete status

Request

Path Parameters

Headers

Response

200: Success

with media

with poll

401: Unauthorized

404: Not Found

get Parent and child statuses

Request

Path Parameters

Headers

Response

200: Success

404: Not Found

get Boosted by

Request

Path Parameters

Response

200: Success

404: Not Found

get Favourited by

Request

Path Parameters

Response

200: Success

404: Not Found

post Favourite

Request

Path Parameters

Headers

Response

200: Success

401: Unauthorized

404: Not Found

post Undo favourite

Request

Path Parameters

Headers

Response

200: Success

401: Unauthorized

404: Not Found

post Boost

Request

Path Parameters

Headers

Form Data Parameters

Response

200: Success

401: Unauthorized

404: Not Found

post Undo boost

Request

Path Parameters

Headers

Response

200: Success

401: Unauthorized

404: Not Found

post Bookmark

post
Publish new status

get
View specific status

delete
Delete status

get
Parent and child statuses

get
Boosted by

get
Favourited by

post
Favourite

post
Undo favourite

post
Boost

post
Undo boost

post
Bookmark

post
Undo bookmark

post
Mute conversation

post
Unmute conversation

post
Pin to profile

post
Unpin to profile

get
Preview card