statuses

Publish, interact, and view information about statuses.

Publish new status

POST 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

Headers

Name	Type	Description
Idempotency-Key	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	string	Bearer <user token>

Request Body

Name	Type	Description
status	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[]	array	Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used.
poll[options][]	array	Array of possible answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided.
poll[expires_in]	number	Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided.
poll[multiple]	boolean	Allow multiple choices?
poll[hide_totals]	boolean	Hide vote counts until the poll ends?
in_reply_to_id	string	ID of the status being replied to, if status is a reply
sensitive	boolean	Mark status and attached media as sensitive?
spoiler_text	string	Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.
visibility	string	Visibility of the posted status. Enumerable oneOf public, unlisted, private, direct.
scheduled_at	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	string	ISO 639 language code for this status.

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

View specific status

GET 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200

{
  "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 instance is in whitelist mode

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

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

{
  "error": "Record not found"
}

Delete status

DELETE 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database. Must be owned by authenticated account.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Parent and child statuses

GET 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200

{
  "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 Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}

Boosted by

GET 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

200

[
  {
    "id": "711345",
    "username": "Norman_Doors",
    "acct": "[e-mail]",
    ...
  },
  ...
]

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

{
  "error": "Record not found"
}

Favourited by

GET 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

200

[
  {
    "id": "828600",
    "username": "fructose_dealer",
    "acct": "[e-mail]",
    ...
  },
  ...
]

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

{
  "error": "Record not found"
}

Favourite

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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

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

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

{
  "error": "Record not found"
}

Undo favourite

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Boost

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

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

200 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 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Undo boost

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing authorization header

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

404 Status deleted, does not exist, or no reblog exists

{
 "error":  "Record not found"
}

Bookmark

POST 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

Path Parameters

Name	Type	Description
:id	string	ID of the status in the database

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Status bookmarked

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

401 Invalid or missing Authorization header

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

404

{
  "error": "Record not found"
}

Undo bookmark

POST 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

Path Parameters

Name	Type	Description
id	string	ID of the status in the database

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200

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

401 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Mute conversation

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

404

{
  "error": "Record not found"
}

Unmute conversation

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

404

{
  "error": "Record not found"
}

Pin to profile

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database. The status should be public and authored by the authorized account.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

422 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"
}

Unpin to profile

POST 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

Path Parameters

Name	Type	Description
:id	string	Local ID of a status in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

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

{
  "error": "Record not found"
}

Deprecated methods

Preview card

GET 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

Path Parameters

Name	Type	Description
:id	string	ID of the status in the database

200

{
  "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 Status does not exist, is deleted, or is private

{
  "error": "Record not found"
}