You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

327 lines
9.4 KiB

  1. API overview
  2. ============
  3. ## Contents
  4. - [Available libraries](#available-libraries)
  5. - [Notes](#notes)
  6. - [Methods](#methods)
  7. - Posting a status
  8. - Uploading media
  9. - Retrieving a timeline
  10. - Retrieving notifications
  11. - Following a remote user
  12. - Fetching data
  13. - Deleting a status
  14. - Reblogging a status
  15. - Favouriting a status
  16. - Threads (status context)
  17. - Who reblogged/favourited a status
  18. - Following/unfollowing accounts
  19. - Blocking/unblocking accounts
  20. - Getting instance information
  21. - Creating OAuth apps
  22. - [Entities](#entities)
  23. - Status
  24. - Account
  25. - [Pagination](#pagination)
  26. ## Available libraries
  27. - [For Ruby](https://github.com/tootsuite/mastodon-api)
  28. - [For Python](https://github.com/halcy/Mastodon.py)
  29. - [For JavaScript](https://github.com/Zatnosk/libodonjs)
  30. - [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon)
  31. ## Notes
  32. When an array parameter is mentioned, the Rails convention of specifying array parameters in query strings is meant. For example, a ruby array like `foo = [1, 2, 3]` can be encoded in the params as `foo[]=1&foo[]=2&foo[]=3`. Square brackets can be indexed but can also be empty.
  33. When a file parameter is mentioned, a form-encoded upload is expected.
  34. ## Methods
  35. ### Posting a new status
  36. **POST /api/v1/statuses**
  37. Form data:
  38. - `status`: The text of the status
  39. - `in_reply_to_id` (optional): local ID of the status you want to reply to
  40. - `media_ids` (optional): array of media IDs to attach to the status (maximum 4)
  41. - `sensitive` (optional): set this to mark the media of the status as NSFW
  42. - `visibility` (optional): either `private`, `unlisted` or `public`
  43. - `spoiler_text` (optional): text to be shown as a warning before the actual content
  44. Returns the new status.
  45. **POST /api/v1/media**
  46. Form data:
  47. - `file`: Image to be uploaded
  48. Returns a media object with an ID that can be attached when creating a status (see above).
  49. ### Retrieving a timeline
  50. **GET /api/v1/timelines/home**
  51. **GET /api/v1/timelines/public**
  52. **GET /api/v1/timelines/tag/:hashtag**
  53. Returns statuses, most recent ones first. Home timeline is statuses from people you follow, mentions timeline is all statuses that mention you. Public timeline is "whole known network", and the last is the hashtag timeline.
  54. Query parameters:
  55. - `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time)
  56. - `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
  57. Query parameters for public and tag timelines only:
  58. - `local` (optional): Only return statuses originating from this instance
  59. ### Notifications
  60. **GET /api/v1/notifications**
  61. Returns notifications for the authenticated user. Each notification has an `id`, a `type` (mention, reblog, favourite, follow), an `account` which it came *from*, and in case of mention, reblog and favourite also a `status`.
  62. **GET /api/v1/notifications/:id**
  63. Returns single notification.
  64. **POST /api/v1/notifications/clear**
  65. Clears all of user's notifications.
  66. ### Following a remote user
  67. **POST /api/v1/follows**
  68. Form data:
  69. - uri: username@domain of the person you want to follow
  70. Returns the local representation of the followed account.
  71. ### Fetching data
  72. **GET /api/v1/statuses/:id**
  73. Returns status.
  74. **GET /api/v1/accounts/:id**
  75. Returns account.
  76. **GET /api/v1/accounts/verify_credentials**
  77. Returns authenticated user's account.
  78. **GET /api/v1/accounts/:id/statuses**
  79. Returns statuses by user.
  80. Query parameters:
  81. - `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time)
  82. - `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
  83. - `only_media` (optional): Only return statuses that have media attachments
  84. - `exclude_replies` (optional): Skip statuses that reply to other statuses
  85. **GET /api/v1/accounts/:id/following**
  86. Returns users the given user is following.
  87. **GET /api/v1/accounts/:id/followers**
  88. Returns users the given user is followed by.
  89. **GET /api/v1/accounts/relationships**
  90. Returns relationships (`following`, `followed_by`, `blocking`, `muting`, `requested`) of the current user to a list of given accounts.
  91. Query parameters:
  92. - `id` (can be array): Account IDs
  93. **GET /api/v1/accounts/search**
  94. Returns matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database.
  95. Query parameters:
  96. - `q`: what to search for
  97. - `limit`: maximum number of matching accounts to return
  98. **GET /api/v1/blocks**
  99. Returns accounts blocked by authenticated user.
  100. **GET /api/v1/mutes**
  101. Returns accounts muted by authenticated user.
  102. **GET /api/v1/follow_requests**
  103. Returns accounts that want to follow the authenticated user but are waiting for approval.
  104. **GET /api/v1/favourites**
  105. Returns statuses favourited by authenticated user.
  106. ### Deleting a status
  107. **DELETE /api/v1/statuses/:id**
  108. Returns an empty object.
  109. ### Reblogging a status
  110. **POST /api/v1/statuses/:id/reblog**
  111. Returns a new status that wraps around the reblogged one.
  112. ### Unreblogging a status
  113. **POST /api/v1/statuses/:id/unreblog**
  114. Returns the status that used to be reblogged.
  115. ### Favouriting a status
  116. **POST /api/v1/statuses/:id/favourite**
  117. Returns the target status.
  118. ### Unfavouriting a status
  119. **POST /api/v1/statuses/:id/unfavourite**
  120. Returns the target status.
  121. ### Threads
  122. **GET /api/v1/statuses/:id/context**
  123. Returns `ancestors` and `descendants` of the status.
  124. ### Who reblogged/favourited a status
  125. **GET /api/v1/statuses/:id/reblogged_by**
  126. **GET /api/v1/statuses/:id/favourited_by**
  127. Returns list of accounts.
  128. ### Following and unfollowing users
  129. **POST /api/v1/accounts/:id/follow**
  130. **POST /api/v1/accounts/:id/unfollow**
  131. Returns the updated relationship to the user.
  132. ### Blocking and unblocking users
  133. **POST /api/v1/accounts/:id/block**
  134. **POST /api/v1/accounts/:id/unblock**
  135. Returns the updated relationship to the user.
  136. ### Getting instance information
  137. **GET /api/v1/instance**
  138. Returns an object containing the `title`, `description`, `email` and `uri` of the instance. Does not require authentication.
  139. # Muting and unmuting users
  140. **POST /api/v1/accounts/:id/mute**
  141. **POST /api/v1/accounts/:id/unmute**
  142. Returns the updated relationship to the user.
  143. ### OAuth apps
  144. **POST /api/v1/apps**
  145. Form data:
  146. - `client_name`: Name of your application
  147. - `redirect_uris`: Where the user should be redirected after authorization (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`)
  148. - `scopes`: This can be a space-separated list of the following items: "read", "write" and "follow" (see [this page](OAuth-details.md) for details on what the scopes do)
  149. - `website`: (optional) URL to the homepage of your app
  150. Creates a new OAuth app. Returns `id`, `client_id` and `client_secret` which can be used with [OAuth authentication in your 3rd party app](Testing-with-cURL.md).
  151. These values should be requested in the app itself from the API for each new app install + mastodon domain combo, and stored in the app for future requests.
  152. ___
  153. ## Entities
  154. ### Status
  155. | Attribute | Description |
  156. |---------------------|-------------|
  157. | `id` ||
  158. | `uri` | fediverse-unique resource ID |
  159. | `url` | URL to the status page (can be remote) |
  160. | `account` | Account |
  161. | `in_reply_to_id` | null or ID of status it replies to |
  162. | `reblog` | null or Status|
  163. | `content` | Body of the status. This will contain HTML (remote HTML already sanitized) |
  164. | `created_at` ||
  165. | `reblogs_count` ||
  166. | `favourites_count` ||
  167. | `reblogged` | Boolean for authenticated user |
  168. | `favourited` | Boolean for authenticated user |
  169. | `sensitive` | Boolean, true if media attachments should be hidden by default |
  170. | `spoiler_text` | If not empty, warning text that should be displayed before the actual content |
  171. | `visibility` | Either `public`, `unlisted` or `private` |
  172. | `media_attachments` | array of MediaAttachments |
  173. | `mentions` | array of Mentions |
  174. | `application` | Application from which the status was posted |
  175. Media Attachment:
  176. | Attribute | Description |
  177. |---------------------|-------------|
  178. | `url` | URL of the original image (can be remote) |
  179. | `preview_url` | URL of the preview image |
  180. | `type` | Image or video |
  181. Mention:
  182. | Attribute | Description |
  183. |---------------------|-------------|
  184. | `url` | URL of user's profile (can be remote) |
  185. | `acct` | Username for local or username@domain for remote users |
  186. | `id` | Account ID |
  187. Application:
  188. | Attribute | Description |
  189. |---------------------|-------------|
  190. | `name` | Name of the app |
  191. | `website` | Homepage URL of the app |
  192. ### Account
  193. | Attribute | Description |
  194. |-------------------|-------------|
  195. | `id` ||
  196. | `username` ||
  197. | `acct` | Equals username for local users, includes @domain for remote ones |
  198. | `display_name` ||
  199. | `note` | Biography of user |
  200. | `url` | URL of the user's profile page (can be remote) |
  201. | `avatar` | URL to the avatar image |
  202. | `header` | URL to the header image |
  203. | `locked` | Boolean for when the account cannot be followed without waiting for approval first |
  204. | `followers_count` ||
  205. | `following_count` ||
  206. | `statuses_count` ||
  207. ## Pagination
  208. API methods that return collections of items can return a `Link` header containing URLs for the `next` and `prev` pages. [Link header RFC](https://tools.ietf.org/html/rfc5988)