From 243fc1d5e17f395ae8f62156e7ad415c428cd8fe Mon Sep 17 00:00:00 2001
From: noellabo <noel.yoshiba@gmail.com>
Date: Sun, 27 Jan 2019 14:01:33 +0100
Subject: [PATCH] Add REST API for scheduled statuses

---
 content/en/api/entities.md                | 22 ++++++++++
 content/en/api/rest/scheduled-statuses.md | 51 +++++++++++++++++++++++
 content/en/api/rest/statuses.md           | 14 +++++++
 3 files changed, 87 insertions(+)
 create mode 100644 content/en/api/rest/scheduled-statuses.md

diff --git a/content/en/api/entities.md b/content/en/api/entities.md
index 931e3653..bae77d8f 100644
--- a/content/en/api/entities.md
+++ b/content/en/api/entities.md
@@ -310,6 +310,28 @@ Please check `app/javascript/mastodon/selectors/index.js` and `app/lib/feed_mana
 - `private`
 - `direct`
 
+## ScheduledStatus
+
+|Attribute|Type|Nullable|Added in|
+|---------|-----------|:------:|:------:|
+| `id` | String |{{< no >}}|2.7.0|
+| `scheduled_at` | String (Datetime) |{{< no >}}|2.7.0|
+| `params` | Array of [Hash](#statusparams) |{{< no >}}|2.7.0|
+| `media_attachments` | Array of [Attachment](#attachment) |{{< no >}}|2.7.0|
+
+### StatusParams
+
+|Attribute|Type|Nullable|Added in|
+|---------|-----------|:------:|:------:|
+| `text` | String |{{< no >}}|2.7.0|
+| `in_reply_to_id` | String |{{< yes >}}|2.7.0|
+| `media_ids` | Array of String |{{< yes >}}|2.7.0|
+| `sensitive` | Boolean |{{< yes >}}|2.7.0|
+| `spoiler_text` | String |{{< yes >}}|2.7.0|
+| `visibility` | [String (Enum)](#visibility) |{{< no >}}|2.7.0|
+| `scheduled_at` | String (Datetime) |{{< yes >}}|2.7.0|
+| `application_id` | String |{{< no >}}|2.7.0|
+
 ## Tag
 
 |Attribute|Type|Nullable|Added in|
diff --git a/content/en/api/rest/scheduled-statuses.md b/content/en/api/rest/scheduled-statuses.md
new file mode 100644
index 00000000..07bcfffa
--- /dev/null
+++ b/content/en/api/rest/scheduled-statuses.md
@@ -0,0 +1,51 @@
+---
+title: Scheduled Statuses
+menu:
+  docs:
+    parent: rest-api
+    weight: 10
+---
+
+## GET /api/v1/scheduled_statuses
+
+Get scheduled statuses.
+
+Returns array of [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}}
+
+## GET /api/v1/scheduled_statuses/:id
+
+Get scheduled status.
+
+Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="2.7.0" >}}
+
+## PUT /api/v1/scheduled_statuses/:id
+
+Update Scheduled status. Only `scheduled_at` can be changed. To change the content, delete it and post a new status.
+
+Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}}
+
+### Parameters
+
+|Name|Description|Required|
+|----|-----------|:------:|
+| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |
+
+## DELETE /api/v1/scheduled_statuses/:id
+
+Remove Scheduled status.
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="2.7.0" >}}
diff --git a/content/en/api/rest/statuses.md b/content/en/api/rest/statuses.md
index 3a29339f..fbf878ae 100644
--- a/content/en/api/rest/statuses.md
+++ b/content/en/api/rest/statuses.md
@@ -80,6 +80,9 @@ Publish a new status.
 
 Returns [Status]({{< relref "entities.md#status" >}})
 
+When `scheduled_at` option is present,
+Returns [ScheduledStatus]({{< relref "entities.md#scheduledstatus" >}}) 
+
 ### Resource information
 
 {{< api_method_info auth="Yes" user="Yes" scope="write write:statuses" version="0.0.0" >}}
@@ -94,6 +97,7 @@ Returns [Status]({{< relref "entities.md#status" >}})
 | `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 |
+| `scheduled_at` | Timestamp string to schedule posting of status (ISO 8601) | Optional |
 | `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.
@@ -104,6 +108,16 @@ In order to prevent duplicate statuses, this endpoint accepts an `Idempotency-Ke
 
 See <https://stripe.com/blog/idempotency> for more on idempotency and idempotency keys.
 
+### 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.
+
 ## DELETE /api/v1/statuses/:id
 
 Remove a status. The status may still be available a short while after the call.