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
id
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