statuses.md 5.68 KB
Newer Older
Eugen Rochko's avatar
Eugen Rochko committed
1
---
Eugen Rochko's avatar
Eugen Rochko committed
2
title: Statuses
Eugen Rochko's avatar
Eugen Rochko committed
3 4
menu:
  docs:
Eugen Rochko's avatar
Eugen Rochko committed
5
    parent: rest-api
Eugen Rochko's avatar
Eugen Rochko committed
6 7
    weight: 10
---
Eugen Rochko's avatar
Eugen Rochko committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82

## GET /api/v1/statuses/:id

Returns [Status]({{< relref "entities.md#status" >}})

### Resource information

{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}

## GET /api/v1/statuses/:id/context

What the status replies to, and replies to it.

Returns [Context]({{< relref "entities.md#context" >}})

### Resource information

{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}

## GET /api/v1/statuses/:id/card

Link preview card for a status, if available.

Returns [Card]({{< relref "entities.md#card" >}})

### Resource information

{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}

## GET /api/v1/statuses/:id/reblogged_by

Accounts that reblogged the status.

Returns array of [Account]({{< relref "entities.md#account" >}})

### Resource information

{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |

### Pagination

{{< api_pagination >}}

## GET /api/v1/statuses/:id/favourited_by

Accounts that favourited the status.

Returns array of [Account]({{< relref "entities.md#account" >}})

### Resource information

{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `limit` | Maximum number of results | Optional | 40 |

### Pagination

{{< api_pagination >}}

## POST /api/v1/statuses

Publish a new status.

Returns [Status]({{< relref "entities.md#status" >}})

83 84 85
When `scheduled_at` option is present,
Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) 

Eugen Rochko's avatar
Eugen Rochko committed
86 87 88 89 90 91
### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}

### Parameters

92 93
|Name|Description|Required|Added in|
|----|-----------|:------:|:------:|
Eugen Rochko's avatar
Eugen Rochko committed
94 95 96
| `status` | The text of the status | Optional\* |
| `in_reply_to_id` | ID of the status you want to reply to | Optional |
| `media_ids` | Array of media IDs to attach to the status | Optional\* |
97
| `poll` | Nested parameters to attach a poll to the status | Optional\* |2.8.0|
Eugen Rochko's avatar
Eugen Rochko committed
98 99 100
| `sensitive` | Mark the media in the status as sensitive | Optional |
| `spoiler_text` | Text to be shown as a warning before the actual content | Optional |
| `visibility` | One of `direct`, `private`, `unlisted` `public` | Optional |
101
| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |2.7.0|
Eugen Rochko's avatar
Eugen Rochko committed
102 103
| `language` | Override language code of the toot (ISO 639-2) | Optional |

104 105 106 107 108 109 110 111 112 113
> You must provide either `status` or `media_ids`, completely empty statuses are not allowed. Polls require a `status` and cannot be combined with `media_ids`.

Poll parameters:

|Name|Description|Required|
|----|-----------|:------:|
| `poll[options]` | Array of poll answer strings | Required |
| `poll[expires_in]` | Duration the poll should be open for in seconds | Required |
| `poll[multiple]` | Whether multiple choices should be allowed | Optional |
| `poll[hide_totals]` | Whether to hide totals until the poll ends | Optional |
Eugen Rochko's avatar
Eugen Rochko committed
114 115 116 117 118 119 120

### Idempotency

In order to prevent duplicate statuses, this endpoint accepts an `Idempotency-Key` header, which should be set to a unique string for each new status. In the event of a network error, a request can be retried with the same `Idempotency-Key`. Only one status will be created regardless of how many requests with the same `Idempotency-Key` did go through.

See <https://stripe.com/blog/idempotency> for more on idempotency and idempotency keys.

121 122 123 124 125 126 127 128 129 130
### Scheduled status

Allows users to schedule a toot (with media attachments) to be published at a certain future date.

The scheduled date must be at least 5 minutes into the future. At most, 300 toots can be scheduled at the same time. Only 50 toots can be scheduled for any given day.

When `scheduled_at` option is present, instead of creating a status, we only run status validation, and if it passes, we create an entry in scheduled_statuses which encodes the status attributes.  Every 5 minutes, a scheduler iterates over the scheduled_statuses table to fetch the ones due in the next 5 minutes, and push them into a more precise Sidekiq queue. In Sidekiq, the individual statuses are created, with media attachments being unassigned from the scheduled status and assigned to the real one.

This option was added since v2.7.0.

Eugen Rochko's avatar
Eugen Rochko committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
## DELETE /api/v1/statuses/:id

Remove a status. The status may still be available a short while after the call.

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}

## POST /api/v1/statuses/:id/reblog

Reblog a status.

Returns [Status]({{< relref "entities.md#status" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}

## POST /api/v1/statuses/:id/unreblog

Undo the reblog of a status.

Returns [Status]({{< relref "entities.md#status" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}

## POST /api/v1/statuses/:id/pin

Pin user's own status to user's profile.

Returns [Status]({{< relref "entities.md#status" >}})

### Resource information

167
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
168 169 170 171 172 173 174 175 176

## POST /api/v1/statuses/:id/unpin

Remove pinned status from user's profile.

Returns [Status]({{< relref "entities.md#status" >}})

### Resource information

177
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}}