From b2023264a211b0b0b64c9b077ee7bdc6845f63b9 Mon Sep 17 00:00:00 2001 From: Eugen Rochko Date: Sat, 6 Oct 2018 01:09:03 +0200 Subject: [PATCH] Add statuses API --- content/en/api/rest/apps.md | 10 ++ content/en/api/rest/favourites.md | 16 ++++ content/en/api/rest/mutes.md | 20 ++++ content/en/api/rest/statuses.md | 154 +++++++++++++++++++++++++++++- 4 files changed, 198 insertions(+), 2 deletions(-) diff --git a/content/en/api/rest/apps.md b/content/en/api/rest/apps.md index e1b04c74..b0558316 100644 --- a/content/en/api/rest/apps.md +++ b/content/en/api/rest/apps.md @@ -26,3 +26,13 @@ Returns [App]({{< relref "entities.md#app" >}}) with `client_id` and `client_sec | `website` | URL to the homepage of your app | Optional | > To display the authorization code to the end-user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in `redirect_uris` + +## GET /api/v1/apps/verify_credentials + +Confirm that the app's OAuth2 credentials work. + +Returns [App]({{< relref "entities.md#app" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="No" version="0.0.0" >}} diff --git a/content/en/api/rest/favourites.md b/content/en/api/rest/favourites.md index c044567f..fa4e15c2 100644 --- a/content/en/api/rest/favourites.md +++ b/content/en/api/rest/favourites.md @@ -25,3 +25,19 @@ Returns array of [Status]({{< relref "entities.md#status" >}}) ### Pagination {{< api_pagination >}} + +## POST /api/v1/statuses/:id/favourite + +Favourite a status. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/unfavourite + +Undo the favourite of a status. + +Returns [Status]({{< relref "entities.md#status" >}}) diff --git a/content/en/api/rest/mutes.md b/content/en/api/rest/mutes.md index d37ba766..1b31b8b8 100644 --- a/content/en/api/rest/mutes.md +++ b/content/en/api/rest/mutes.md @@ -51,3 +51,23 @@ Returns [Relationship]({{< relref "entities.md#relationship" >}}) ### Resource information {{< api_method_info auth="Yes" user="Yes" scope="write:mutes follow" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/mute + +Mute the conversation the status is part of, to no longer be notified about it. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/unmute + +Unmute the conversation the status is part of. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:mutes" version="0.0.0" >}} diff --git a/content/en/api/rest/statuses.md b/content/en/api/rest/statuses.md index a3bdacf6..80aba1f0 100644 --- a/content/en/api/rest/statuses.md +++ b/content/en/api/rest/statuses.md @@ -1,7 +1,157 @@ --- -title: Statuses API +title: Statuses menu: docs: - parent: api + parent: rest-api weight: 10 --- + +## 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" >}}) + +### 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 | +| `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 for more on idempotency and idempotency keys. + +## 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" >}} + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:favourites" 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 + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}} + +## POST /api/v1/statuses/:id/unpin + +Remove pinned status from user's profile. + +Returns [Status]({{< relref "entities.md#status" >}}) + +### Resource information + +{{< api_method_info auth="Yes" user="Yes" scope="write write:accounts" version="0.0.0" >}}