2023-12-06 12:57:15 +01:00
2020-01-01 22:37:59 +01:00
---
2022-11-20 07:34:38 +01:00
title: statuses API methods
description: Publish, interact, and view information about statuses.
2020-01-01 22:37:59 +01:00
menu:
docs:
weight: 30
2022-11-20 07:34:38 +01:00
name: statuses
2020-01-01 22:37:59 +01:00
parent: methods
identifier: methods-statuses
2022-11-20 07:34:38 +01:00
aliases: [
"/methods/statuses",
"/api/methods/statuses",
]
2020-01-01 22:37:59 +01:00
---
2022-11-20 07:34:38 +01:00
< style >
#TableOfContents ul ul ul {display: none}
< / style >
2022-12-14 22:55:30 +01:00
## Post a new status {#create}
2022-11-20 07:34:38 +01:00
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
2022-12-14 22:55:30 +01:00
Publish a status with the given parameters.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{<relref "entities/status">}} ). When `scheduled_at` is present, [ScheduledStatus ]({{<relref "entities/scheduledstatus">}} ) is returned instead.\
2020-01-01 22:37:59 +01:00
**OAuth:** User + `write:statuses` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added\
2.7.0 - `scheduled_at` added\
2.8.0 - `poll` added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
Idempotency-Key
: Provide this header with any arbitrary string to prevent duplicate submissions of the same status. Consider using a hash or UUID generated client-side. Idempotency keys are stored for up to 1 hour.
##### Form data parameters
status
: {{< required > }} String. The 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 of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used.
poll[options][]
: {{< required > }} Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided.
poll[expires_in]
: {{< required > }} Integer. Duration that 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? Defaults to false.
poll[hide_totals]
: Boolean. Hide vote counts until the poll ends? Defaults to false.
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? Defaults to false.
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. Sets the visibility of the posted status to `public` , `unlisted` , `private` , `direct` .
language
: String. ISO 639 language code for this status.
scheduled_at
2022-12-14 22:55:30 +01:00
: String. ISO 8601 Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
Status will be posted with chosen parameters:
```json
2020-01-01 22:37:59 +01:00
{
"id": "103254962155278888",
"created_at": "2019-12-05T11:34:47.196Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"content": "< p > test content< / p > ",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"application": {
"name": "test app",
"website": null
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
If scheduled_at is provided, then a ScheduledStatus will be returned instead:
```json
2020-01-01 22:37:59 +01:00
{
"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": []
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
##### 422: Unprocessable entity
```json
{
"error": "Validation failed: Text can't be blank"
}
```
---
## View a single status {#get}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Obtain information about a status.
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added\
2.7.0 - public statuses no longer require token
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
2020-01-01 22:37:59 +01:00
{
"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
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Instance is in authorized-fetch mode.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "This API requires an authenticated user"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
2024-04-24 16:01:25 +02:00
## View multiple statuses {#index}
```http
GET /api/v1/statuses HTTP/1.1
```
Obtain information about multiple statuses.
**Returns:** Array of [Status ]({{< relref "entities/status" >}} )\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
**Version history:**\
4.3.0 - added
#### Request
##### Query parameters
id[]
: Array of String. The IDs of the Statuses in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
[Status ]({{< relref "entities/status" >}} ) records for the requested statuses will be returned. There can be fewer records than requested if the requested statuses do not exist or cannot be accessed given the current credentials.
Sample call with `id[]=1&id[]=2` when no status with `id=2` exists:
```json
[
{
"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 authorized-fetch mode.
```json
{
"error": "This API requires an authenticated user"
}
```
---
2022-11-20 07:34:38 +01:00
## Delete a status {#delete}
```http
2022-12-14 22:55:30 +01:00
DELETE /api/v1/statuses/:id HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Delete one of your own statuses.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} ) with source `text` and `poll` or `media_attachments` \
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:statuses` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added\
2.9.0 - return source properties, for use with delete and redraft
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Note the special properties `text` and `poll` or `media_attachments` which may be used to repost the status, e.g. in case of delete-and-redraft functionality. With [POST /api/v1/statuses ](#create ), 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.
Example of deleting a media post:
```json
2020-01-01 22:37:59 +01:00
{
"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 ⴳ",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
"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
}
```
2022-11-20 07:34:38 +01:00
Example of deleting a poll:
```json
2020-01-01 22:37:59 +01:00
{
"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 ⴳ",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
"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": []
}
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status is not owned by you or does not exist
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Get parent and child statuses in context {#context}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/context HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
View statuses above and below this status in the thread.
2022-11-20 07:34:38 +01:00
**Returns:** [Context ]({{< relref "entities/context" >}} )\
2023-07-11 15:19:33 +02:00
**OAuth:** Public for public statuses limited to 40 ancestors and 60 descendants with a maximum depth of 20. User token + `read:statuses` for up to 4,096 ancestors, 4,096 descendants, unlimited depth, and private statuses.\
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2023-07-11 15:19:33 +02:00
4.0.0 - limit unauthenticated requests
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
2020-01-01 22:37:59 +01:00
{
"ancestors": [
{
"id": "103188938570975982",
"created_at": "2019-11-23T19:44:00.124Z",
"in_reply_to_id": null,
"in_reply_to_account_id": null,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
{
"id": "103188971072973252",
"created_at": "2019-11-23T19:52:23.398Z",
"in_reply_to_id": "103188938570975982",
"in_reply_to_account_id": "634458",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
{
"id": "103188982235527758",
"created_at": "2019-11-23T19:55:08.208Z",
"in_reply_to_id": "103188971072973252",
"in_reply_to_account_id": "14715",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
],
"descendants": [
{
"id": "103189026958574542",
"created_at": "2019-11-23T20:06:36.011Z",
"in_reply_to_id": "103189005915505698",
"in_reply_to_account_id": "634458",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
]
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status is private or does not exist
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
2023-02-07 02:14:07 +01:00
## Translate a status {#translate}
```http
POST /api/v1/statuses/:id/translate HTTP/1.1
```
Translate the status content into some language.
**Returns:** [Translation ]({{< relref "entities/translation" >}} )\
**OAuth:** App token + `read:statuses` \
**Version history:**\
4.0.0 - added
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Form data parameters
lang
: String (ISO 639 language code). The status content will be translated into this language. Defaults to the user's current locale.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
2023-12-10 19:44:53 +01:00
Translating a status in Spanish with content warning and media into English
2023-02-07 02:14:07 +01:00
```json
{
2023-12-10 19:44:53 +01:00
"content": "< p > Hello world< / p > ",
"spoiler_text": "Greatings ahead",
"media_attachments": [
{
"id": 22345792,
"description": "Status author waving at the camera"
}
],
"poll": null,
"detected_source_language": "es",
"provider": "DeepL.com"
}
```
Translating a status with poll into English
```json
{
"content": "< p > Should I stay or should I go?< / p > ",
"spoiler_text": null,
"media_attachments": [],
"poll": [
{
"id": 34858,
"options": [
{
"title": "Stay"
},
{
"title": "Go"
}
]
}
],
"detected_source_language": "ja",
2023-02-07 02:14:07 +01:00
"provider": "DeepL.com"
}
```
##### 404: Not found
Status is private or does not exist
```json
{
"error": "Record not found"
}
```
##### 503: Service unavailable
The translation request failed
```json
{
"error": "Service Unavailable"
}
```
---
2022-11-20 07:34:38 +01:00
## See who boosted a status {#reblogged_by}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/reblogged_by HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
View who boosted a given status.
2022-11-20 07:34:38 +01:00
**Returns:** Array of [Account ]({{< relref "entities/account" >}} )\
**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2022-12-14 22:55:30 +01:00
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
2023-04-07 09:01:21 +02:00
A list of accounts that boosted the status
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
[
{
"id": "711345",
"username": "Norman_Doors",
"acct": "Norman_Doors@witches.live",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
]
```
2022-12-14 22:55:30 +01:00
Because reblogged Status IDs are generally not known ahead of time, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses ]({{<relref "api/guidelines#pagination">}} ) for more information.
```http
Link: < https: / / mastodon . example / api / v1 / statuses / 109404970108594430 / reblogged_by ? limit = 2&max_id=109406336446186031 > ; rel="next", < https: / / mastodon . example / api / v1 / statuses / 109404970108594430 / reblogged_by ? limit = 2&since_id=109408462939099398 > ; rel="prev"
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## See who favourited a status {#favourited_by}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/favourited_by HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
View who favourited a given status.
2022-11-20 07:34:38 +01:00
**Returns:** Array of [Account ]({{< relref "entities/account" >}} )\
**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.\
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2022-12-14 22:55:30 +01:00
##### Query parameters
max_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
since_id
: **Internal parameter.** Use HTTP `Link` header for pagination.
limit
: Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts.
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
A list of accounts who favourited the status
```json
2020-01-01 22:37:59 +01:00
[
{
"id": "828600",
"username": "fructose_dealer",
"acct": "fructose_dealer@radical.town",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
]
```
2022-12-14 22:55:30 +01:00
Because Favourite IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses ]({{<relref "api/guidelines#pagination">}} ) for more information.
```http
Link: < https: / / mastodon . example / api / v1 / statuses / 109419880690343548 / favourited_by ? limit = 1&max_id=53286827 > ; rel="next", < https: / / mastodon . example / api / v1 / statuses / 109419880690343548 / favourited_by ? limit = 1&since_id=53286827 > ; rel="prev"
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Favourite a status {#favourite}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/favourite HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Add a status to your favourites list.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:favourites` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Headers
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status favourited or was already favourited
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": true,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Undo favourite of a status {#unfavourite}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/unfavourite HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Remove a status from your favourites list.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:favourites` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status unfavourited or was already not favourited
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Boost a status {#boost}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/reblog HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Reshare a status on your own profile.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:statuses` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added\
2.8.0 - add `visibility` parameter
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Form data parameters
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
visibility
: String. Any visibility except `limited` or `direct` (i.e. `public` , `unlisted` , `private` ). Defaults to public. Currently unused in UI.
#### Response
##### 200: OK
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.
```json
2020-01-01 22:37:59 +01:00
{
"id": "103254401326800919",
"created_at": "2019-12-05T09:12:09.625Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": true,
"muted": false,
"bookmarked": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"reblog": {
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": true,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Undo boost of a status {#unreblog}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/unreblog HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Undo a reshare of a status.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:statuses` \
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status unboosted or was already not boosted
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
2022-11-20 07:34:38 +01:00
"error": "Record not found"
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
---
## Bookmark a status {#bookmark}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/bookmark HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Privately bookmark a status.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:bookmarks` \
2020-12-27 07:03:55 +01:00
**Version history:**\
3.1.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status bookmarked or was already bookmarked
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": true,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
## Undo bookmark of a status {#unbookmark}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/unbookmark HTTP/1.1
2020-01-01 22:37:59 +01:00
```
Remove a status from your private bookmarks.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:bookmarks` \
2020-12-27 07:03:55 +01:00
**Version history:**\
3.1.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status was unbookmarked or was already not bookmarked
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Mute a conversation {#mute}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/mute HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:mutes` \
2020-12-27 07:03:55 +01:00
**Version history:**\
1.4.2 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Status in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status's conversation muted, or was already muted
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": true,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Unmute a conversation {#unmute}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/unmute HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Start receiving notifications again for the thread that this status is part of.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:mutes` \
2020-12-27 07:03:55 +01:00
**Version history:**\
1.4.2 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
:id
: {{< required > }} String. The ID of the Status in the database.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status's conversation unmuted, or was already unmuted
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## Pin status to profile {#pin}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/pin HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Feature one of your own public statuses at the top of your profile.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:accounts` \
2020-12-27 07:03:55 +01:00
**Version history:**\
2022-11-20 07:34:38 +01:00
1.6.0 - added\
3.5.0 - you can now pin private posts
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The local ID of the Status in the database. The status should be authored by the authorized account.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Response
##### 200: OK
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status pinned. Note the status is not a reblog and its authoring account is your own.
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": true,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"reblog": null,
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
##### 422: Unprocessable entity
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status is not owned by you:
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
2022-11-20 07:34:38 +01:00
"error": "Validation failed: Someone else's post cannot be pinned"
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
Prior to 3.5.0, you could not pin one of your private statuses because private statuses could not be fetched from remote sites, and must have been delivered. (3.5.0 added a mechanism to fetch statuses on behalf of an account.)
```json
2020-01-01 22:37:59 +01:00
{
"error": "Validation failed: Non-public toot cannot be pinned"
}
```
2022-11-20 07:34:38 +01:00
---
## Unpin status from profile {#unpin}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/statuses/:id/unpin HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Unfeature a status from the top of your profile.
2022-11-20 07:34:38 +01:00
**Returns:** [Status ]({{< relref "entities/status" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `write:accounts` \
2020-12-27 07:03:55 +01:00
**Version history:**\
1.6.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
:id
: {{< required > }} String. The local ID of the Status in the database.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Status unpinned, or was already not pinned
```json
2020-01-01 22:37:59 +01:00
{
"id": "99734435964706331",
"created_at": "2018-03-23T17:38:40.700Z",
2022-11-20 07:34:38 +01:00
// ...
"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.
```json
{
"error": "The access token is invalid"
}
```
##### 404: Not found
Status does not exist or is private.
```json
{
"error": "Record not found"
}
```
---
## Edit a status {#edit}
```http
2022-12-14 22:55:30 +01:00
PUT /api/v1/statuses/:id HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Edit a given status to change its text, sensitivity, media attachments, or poll. Note that editing a poll's options will reset the votes.
**Returns:** [Status ]({{< relref "entities/status" >}} )\
**OAuth:** User token + `write:statuses` \
**Version history:**\
2022-12-14 22:55:30 +01:00
3.5.0 - added\
4.0.0 - add `language`
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
2023-02-07 02:14:07 +01:00
: {{< required > }} String. The ID of the Status in the database.
2022-11-20 07:34:38 +01:00
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Form data parameters
status
: String. The plain text content of the status.
spoiler_text
: String. The plain text subject or content warning of the status.
sensitive
: Boolean. Whether the status should be marked as sensitive.
2022-12-14 22:55:30 +01:00
language
: String. ISO 639 language code for the status.
2022-11-20 07:34:38 +01:00
media_ids[]
: Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used.
2023-12-06 12:57:15 +01:00
media_attributes[][]
: Array of String. Each array includes id, description, and focus.
2022-11-20 07:34:38 +01:00
poll[options][]
: Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided.
poll[expires_in]
: Integer. Duration that 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? Defaults to false.
poll[hide_totals]
: Boolean. Hide vote counts until the poll ends? Defaults to false.
#### Response
##### 200: OK
Status has been successfully edited.
```json
{
"id": "108942703571991143",
"created_at": "2022-09-04T23:22:13.704Z",
"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/108942703571991143",
"url": "https://mastodon.social/@trwnh/108942703571991143",
"replies_count": 3,
"reblogs_count": 1,
"favourites_count": 6,
"edited_at": "2022-09-05T00:33:20.309Z",
2020-01-01 22:37:59 +01:00
"favourited": false,
"reblogged": false,
"muted": false,
"bookmarked": false,
"pinned": false,
2022-11-20 07:34:38 +01:00
"content": "< p > this is a status that has been edited multiple times to change the text, add a poll, and change poll options.< / p > ",
"filtered": [],
2020-01-01 22:37:59 +01:00
"reblog": null,
2022-11-20 07:34:38 +01:00
"application": {
"name": "SubwayTooter",
"website": null
},
2020-01-01 22:37:59 +01:00
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
2022-11-20 07:34:38 +01:00
"display_name": "infinite love ⴳ",
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
"media_attachments": [],
"mentions": [],
"tags": [],
"emojis": [],
"card": null,
"poll": null
2020-01-01 22:37:59 +01:00
}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist, is private, or is not owned by you.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
##### 422: Unprocessable entity
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
{
"error": "Validation failed: Text can't be blank"
}
```
---
## View edit history of a status {#history}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/history HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Get all known versions of a status, including the initial and current states.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
**Returns:** Array of [StatusEdit ]({{< relref "entities/statusedit" >}} )\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
**Version history:**\
3.5.0 - added
#### Request
##### Path parameters
:id
: {{< required > }} String. The local ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
[
{
"content": "< p > this is a status that will be edited< / p > ",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-04T23:22:13.704Z",
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
},
{
"content": "< p > this is a status that has been edited< / p > ",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-04T23:22:42.555Z",
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
},
{
"content": "< p > this is a status that has been edited twice< / p > ",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-04T23:22:55.956Z",
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
},
{
"content": "< p > this is a status that has been edited three times. this time a poll has been added.< / p > ",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-05T00:01:48.160Z",
"poll": {
"options": [
{
"title": "cool"
},
{
"title": "uncool"
},
{
"title": "spiderman"
}
]
},
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
},
{
"content": "< p > this is a status that has been edited three times. this time a poll has been added.< / p > ",
"spoiler_text": "",
"sensitive": false,
"created_at": "2022-09-05T00:03:32.480Z",
"poll": {
"options": [
{
"title": "cool"
},
{
"title": "uncool"
},
{
"title": "spiderman (this option has been changed)"
}
]
},
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
"display_name": "infinite love ⴳ",
// ...
},
"media_attachments": [],
"emojis": []
}
]
```
##### 404: Not found
Status does not exist or is private.
```json
{
"error": "Record not found"
}
```
---
## View status source {#source}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/source HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Obtain the source properties for a status so that it can be edited.
**Returns:** [StatusSource ]({{< relref "entities/statussource" >}} )\
**OAuth:** App token + `read:statuses` \
**Version history:**\
3.5.0 - added
#### Request
##### Path parameters
:id
: {{< required > }} String. The local ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
{
"id": "108942703571991143",
"text": "this is a status that will be edited",
"spoiler_text": ""
}
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
##### 404: Not found
Status does not exist or is private.
```json
{
"error": "Record not found"
}
```
---
## (DEPRECATED) Fetch preview card {#card}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/statuses/:id/card HTTP/1.1
2022-11-20 07:34:38 +01:00
```
**Returns:** [PreviewCard ]({{< relref "entities/PreviewCard" >}} )\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
2020-12-27 07:03:55 +01:00
**Version history:**\
0.0.0 - added\
2.6.0 - deprecated in favor of card property inlined on Status entity\
3.0.0 - removed
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Path parameters
:id
: {{< required > }} String. The local ID of the Status in the database.
##### Headers
Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
2020-01-01 22:37:59 +01:00
{
"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": ""
}
```
2022-11-20 07:34:38 +01:00
##### 404: Not found
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Status does not exist or is private.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "Record not found"
}
```
2022-11-20 07:34:38 +01:00
---
## See also
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses_controller.rb" caption = "app/controllers/api/v1/statuses_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/bookmarks_controller.rb" caption = "app/controllers/api/v1/statuses/bookmarks_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" caption = "app/controllers/api/v1/statuses/favourited_by_accounts_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/favourites_controller.rb" caption = "app/controllers/api/v1/statuses/favourites_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/histories_controller.rb" caption = "app/controllers/api/v1/statuses/histories_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/mutes_controller.rb" caption = "app/controllers/api/v1/statuses/mutes_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/pins_controller.rb" caption = "app/controllers/api/v1/statuses/pins_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" caption = "app/controllers/api/v1/statuses/reblogged_by_accounts_controller.rb" > }}
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/reblogs_controller.rb" caption = "app/controllers/api/v1/statuses/reblogs_controller.rb" > }}
2020-01-01 22:37:59 +01:00
2023-04-07 09:01:21 +02:00
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/statuses/sources_controller.rb" caption = "app/controllers/api/v1/statuses/sources_controller.rb" > }}
2023-12-06 12:57:15 +01:00