statuses.md 5.14 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 92 93 94 95 96 97 98 99
### Resource information

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

### Parameters

|Name|Description|Required|
|----|-----------|:------:|
| `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\* |
| `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 |
100
| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |
Eugen Rochko's avatar
Eugen Rochko committed
101 102 103 104 105 106 107 108 109 110
| `language` | Override language code of the toot (ISO 639-2) | Optional |

> You must provide either `status` or `media_ids`, completely empty statuses are not allowed.

### 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.

111 112 113 114 115 116 117 118 119 120
### 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
121 122 123 124 125 126 127 128 129 130 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
## 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

157
{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="1.6.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
158 159 160 161 162 163 164 165 166

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

Remove pinned status from 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" >}}