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.

523 lines
15 KiB

7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
  1. API overview
  2. ============
  3. ## Contents
  4. - [Available libraries](#available-libraries)
  5. - [Notes](#notes)
  6. - [Methods](#methods)
  7. - [Accounts](#accounts)
  8. - [Apps](#apps)
  9. - [Blocks](#blocks)
  10. - [Favourites](#favourites)
  11. - [Follow Requests](#follow-requests)
  12. - [Follows](#follows)
  13. - [Instances](#instances)
  14. - [Media](#media)
  15. - [Mutes](#mutes)
  16. - [Notifications](#notifications)
  17. - [Reports](#reports)
  18. - [Search](#search)
  19. - [Statuses](#statuses)
  20. - [Timelines](#timelines)
  21. - [Entities](#entities)
  22. - [Account](#account)
  23. - [Application](#application)
  24. - [Attachment](#attachment)
  25. - [Card](#card)
  26. - [Context](#context)
  27. - [Error](#error)
  28. - [Instance](#instance)
  29. - [Mention](#mention)
  30. - [Notification](#notification)
  31. - [Relationships](#relationships)
  32. - [Results](#results)
  33. - [Status](#status)
  34. - [Tag](#tag)
  35. ___
  36. ## Available libraries
  37. - [For Ruby](https://github.com/tootsuite/mastodon-api)
  38. - [For Python](https://github.com/halcy/Mastodon.py)
  39. - [For JavaScript](https://github.com/Zatnosk/libodonjs)
  40. - [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon)
  41. ___
  42. ## Notes
  43. ### Parameter types
  44. When an array parameter is mentioned, the Rails convention of specifying array parameters in query strings is meant.
  45. For example, a ruby array like `foo = [1, 2, 3]` can be encoded in the params as `foo[]=1&foo[]=2&foo[]=3`.
  46. Square brackets can be indexed but can also be empty.
  47. When a file parameter is mentioned, a form-encoded upload is expected.
  48. ### Selecting ranges
  49. For most `GET` operations that return arrays, the query parameters `max_id` and `since_id` can be used to specify the range of IDs to return.
  50. API methods that return collections of items can return a `Link` header containing URLs for the `next` and `prev` pages.
  51. See the [Link header RFC](https://tools.ietf.org/html/rfc5988) for more information.
  52. ### Errors
  53. If the request you make doesn't go through, Mastodon will usually respond with an [Error](#error).
  54. ___
  55. ## Methods
  56. ### Accounts
  57. #### Fetching an account:
  58. GET /api/v1/accounts/:id
  59. Returns an [Account](#account).
  60. #### Getting the current user:
  61. GET /api/v1/accounts/verify_credentials
  62. Returns the authenticated user's [Account](#account).
  63. #### Getting an account's followers:
  64. GET /api/v1/accounts/:id/followers
  65. Returns an array of [Accounts](#account).
  66. #### Getting who account is following:
  67. GET /api/v1/accounts/:id/following
  68. Returns an array of [Accounts](#account).
  69. #### Getting an account's statuses:
  70. GET /api/v1/accounts/:id/statuses
  71. Query parameters:
  72. - `only_media` (optional): Only return statuses that have media attachments
  73. - `exclude_replies` (optional): Skip statuses that reply to other statuses
  74. Returns an array of [Statuses](#status).
  75. #### Following/unfollowing an account:
  76. GET /api/v1/accounts/:id/follow
  77. GET /api/v1/accounts/:id/unfollow
  78. Returns the target [Account](#account).
  79. #### Blocking/unblocking an account:
  80. GET /api/v1/accounts/:id/block
  81. GET /api/v1/accounts/:id/unblock
  82. Returns the target [Account](#account).
  83. #### Muting/unmuting an account:
  84. GET /api/v1/accounts/:id/mute
  85. GET /api/v1/accounts/:id/unmute
  86. Returns the target [Account](#account).
  87. #### Getting an account's relationships:
  88. GET /api/v1/accounts/relationships
  89. Query parameters:
  90. - `id` (can be array): Account IDs
  91. Returns an array of [Relationships](#relationships) of the current user to a list of given accounts.
  92. #### Searching for accounts:
  93. GET /api/v1/accounts/search
  94. Query parameters:
  95. - `q`: What to search for
  96. - `limit`: Maximum number of matching accounts to return (default: `40`)
  97. Returns an array of matching [Accounts](#accounts).
  98. Will lookup an account remotely if the search term is in the `username@domain` format and not yet in the database.
  99. ### Apps
  100. #### Registering an application:
  101. POST /api/v1/apps
  102. Form data:
  103. - `client_name`: Name of your application
  104. - `redirect_uris`: Where the user should be redirected after authorization (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`)
  105. - `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)
  106. - `website`: (optional) URL to the homepage of your app
  107. Creates a new OAuth app.
  108. Returns `id`, `client_id` and `client_secret` which can be used with [OAuth authentication in your 3rd party app](Testing-with-cURL.md).
  109. 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.
  110. ### Blocks
  111. #### Fetching a user's blocks:
  112. GET /api/v1/blocks
  113. Returns an array of [Accounts](#account) blocked by the authenticated user.
  114. ### Favourites
  115. #### Fetching a user's favourites:
  116. GET /api/v1/favourites
  117. Returns an array of [Statuses](#status) favourited by the authenticated user.
  118. ### Follow Requests
  119. #### Fetching a list of follow requests:
  120. GET /api/v1/follow_requests
  121. Returns an array of [Accounts](#account) which have requested to follow the authenticated user.
  122. #### Authorizing or rejecting follow requests:
  123. POST /api/v1/follow_requests/authorize
  124. POST /api/v1/follow_requests/reject
  125. Form data:
  126. - `id`: The id of the account to authorize or reject
  127. Returns an empty object.
  128. ### Follows
  129. #### Following a remote user:
  130. POST /api/v1/follows
  131. Form data:
  132. - `uri`: `username@domain` of the person you want to follow
  133. Returns the local representation of the followed account, as an [Account](#account).
  134. ### Instances
  135. #### Getting instance information:
  136. GET /api/v1/instance
  137. Returns the current [Instance](#instance).
  138. Does not require authentication.
  139. ### Media
  140. #### Uploading a media attachment:
  141. POST /api/v1/media
  142. Form data:
  143. - `file`: Media to be uploaded
  144. Returns an [Attachment](#attachment) that can be used when creating a status.
  145. ### Mutes
  146. #### Fetching a user's mutes:
  147. GET /api/v1/mutes
  148. Returns an array of [Accounts](#account) muted by the authenticated user.
  149. ### Notifications
  150. #### Fetching a user's notifications:
  151. GET /api/v1/notifications
  152. Returns a list of [Notifications](#notification) for the authenticated user.
  153. #### Getting a single notification:
  154. GET /api/v1/notifications/:id
  155. Returns the [Notification](#notification).
  156. #### Clearing notifications:
  157. POST /api/v1/notifications/clear
  158. Deletes all notifications from the Mastodon server for the authenticated user.
  159. Returns an empty object.
  160. ### Reports
  161. #### Fetching a user's reports:
  162. GET /api/v1/reports
  163. Returns a list of [Reports](#report) made by the authenticated user.
  164. #### Reporting a user:
  165. POST /api/v1/reports
  166. Form data:
  167. - `account_id`: The ID of the account to report
  168. - `status_ids`: The IDs of statuses to report (can be an array)
  169. - `comment`: A comment to associate with the report.
  170. Returns the finished [Report](#report).
  171. ### Search
  172. #### Searching for content:
  173. GET /api/v1/search
  174. Form data:
  175. - `q`: The search query
  176. - `resolve`: Whether to resolve non-local accounts
  177. Returns [Results](#results).
  178. If `q` is a URL, Mastodon will attempt to fetch the provided account or status.
  179. Otherwise, it will do a local account and hashtag search.
  180. ### Statuses
  181. #### Fetching a status:
  182. GET /api/v1/statuses/:id
  183. Returns a [Status](#status).
  184. #### Getting status context:
  185. GET /api/v1/statuses/:id/contexts
  186. Returns a [Context](#context).
  187. #### Getting a card associated with a status:
  188. GET /api/v1/statuses/:id/card
  189. Returns a [Card](#card).
  190. #### Getting who reblogged/favourited a status:
  191. GET /api/v1/statuses/:id/reblogged_by
  192. GET /api/v1/statuses/:id/favourited_by
  193. Returns an array of [Accounts](#account).
  194. #### Posting a new status:
  195. POST /api/v1/statuses
  196. Form data:
  197. - `status`: The text of the status
  198. - `in_reply_to_id` (optional): local ID of the status you want to reply to
  199. - `media_ids` (optional): array of media IDs to attach to the status (maximum 4)
  200. - `sensitive` (optional): set this to mark the media of the status as NSFW
  201. - `spoiler_text` (optional): text to be shown as a warning before the actual content
  202. - `visibility` (optional): either "direct", "private", "unlisted" or "public"
  203. Returns the new [Status](#status).
  204. #### Deleting a status:
  205. DELETE /api/v1/statuses/:id
  206. Returns an empty object.
  207. #### Reblogging/unreblogging a status:
  208. POST /api/vi/statuses/:id/reblog
  209. POST /api/vi/statuses/:id/unreblog
  210. Returns the target [Status](#status).
  211. #### Favouriting/unfavouriting a status:
  212. POST /api/vi/statuses/:id/favourite
  213. POST /api/vi/statuses/:id/unfavourite
  214. Returns the target [Status](#status).
  215. ### Timelines
  216. #### Retrieving a timeline:
  217. GET /api/v1/timelines/home
  218. GET /api/v1/timelines/public
  219. GET /api/v1/timelines/tag/:hashtag
  220. Query parameters:
  221. - `local` (optional; public and tag timelines only): Only return statuses originating from this instance
  222. Returns an array of [Statuses](#status), most recent ones first.
  223. ___
  224. ## Entities
  225. ### Account
  226. | Attribute | Description |
  227. | ------------------------ | ----------- |
  228. | `id` | The ID of the account |
  229. | `username` | The username of the account |
  230. | `acct` | Equals `username` for local users, includes `@domain` for remote ones |
  231. | `display_name` | The account's display name |
  232. | `note` | Biography of user |
  233. | `url` | URL of the user's profile page (can be remote) |
  234. | `avatar` | URL to the avatar image |
  235. | `header` | URL to the header image |
  236. | `locked` | Boolean for when the account cannot be followed without waiting for approval first |
  237. | `created_at` | The time the account was created |
  238. | `followers_count` | The number of followers for the account |
  239. | `following_count` | The number of accounts the given account is following |
  240. | `statuses_count` | The number of statuses the account has made |
  241. ### Application
  242. | Attribute | Description |
  243. | ------------------------ | ----------- |
  244. | `name` | Name of the app |
  245. | `website` | Homepage URL of the app |
  246. ### Attachment
  247. | Attribute | Description |
  248. | ------------------------ | ----------- |
  249. | `id` | ID of the attachment |
  250. | `type` | One of: "image", "video", "gifv" |
  251. | `url` | URL of the locally hosted version of the image |
  252. | `remote_url` | For remote images, the remote URL of the original image |
  253. | `preview_url` | URL of the preview image |
  254. | `text_url` | Shorter URL for the image, for insertion into text (only present on local images) |
  255. ### Card
  256. | Attribute | Description |
  257. | ------------------------ | ----------- |
  258. | `url` | The url associated with the card |
  259. | `title` | The title of the card |
  260. | `description` | The card description |
  261. | `image` | The image associated with the card, if any |
  262. ### Context
  263. | Attribute | Description |
  264. | ------------------------ | ----------- |
  265. | `ancestors` | The ancestors of the status in the conversation, as a list of [Statuses](#status) |
  266. | `descendants` | The descendants of the status in the conversation, as a list of [Statuses](#status) |
  267. ### Error
  268. | Attribute | Description |
  269. | ------------------------ | ----------- |
  270. | `error` | A textual description of the error |
  271. ### Instance
  272. | Attribute | Description |
  273. | ------------------------ | ----------- |
  274. | `uri` | URI of the current instance |
  275. | `title` | The instance's title |
  276. | `description` | A description for the instance |
  277. | `email` | An email address which can be used to contact the instance administrator |
  278. ### Mention
  279. | Attribute | Description |
  280. | ------------------------ | ----------- |
  281. | `url` | URL of user's profile (can be remote) |
  282. | `username` | The username of the account |
  283. | `acct` | Equals `username` for local users, includes `@domain` for remote ones |
  284. | `id` | Account ID |
  285. ### Notifications
  286. | Attribute | Description |
  287. | ------------------------ | ----------- |
  288. | `id` | The notification ID |
  289. | `type` | One of: "mention", "reblog", "favourite", "follow" |
  290. | `created_at` | The time the notification was created |
  291. | `account` | The [Account](#account) sending the notification to the user |
  292. | `status` | The [Status](#status) associated with the notification, if applicible |
  293. ### Relationships
  294. | Attribute | Description |
  295. | ------------------------ | ----------- |
  296. | `following` | Whether the user is currently following the account |
  297. | `followed_by` | Whether the user is currently being followed by the account |
  298. | `blocking` | Whether the user is currently blocking the account |
  299. | `muting` | Whether the user is currently muting the account |
  300. | `requested` | Whether the user has requested to follow the account |
  301. ### Report
  302. | Attribute | Description |
  303. | ------------------------ | ----------- |
  304. | `id` | The ID of the report |
  305. | `action_taken` | The action taken in response to the report |
  306. ### Results
  307. | Attribute | Description |
  308. | ------------------------ | ----------- |
  309. | `accounts` | An array of matched [Accounts](#account) |
  310. | `statuses` | An array of matchhed [Statuses](#status) |
  311. | `hashtags` | An array of matched hashtags, as strings |
  312. ### Status
  313. | Attribute | Description |
  314. | ------------------------ | ----------- |
  315. | `id` | The ID of the status |
  316. | `uri` | A Fediverse-unique resource ID |
  317. | `url` | URL to the status page (can be remote) |
  318. | `account` | The [Account](#account) which posted the status |
  319. | `in_reply_to_id` | `null` or the ID of the status it replies to |
  320. | `in_reply_to_account_id` | `null` or the ID of the account it replies to |
  321. | `reblog` | `null` or the reblogged [Status](#status) |
  322. | `content` | Body of the status; this will contain HTML (remote HTML already sanitized) |
  323. | `created_at` | The time the status was created |
  324. | `reblogs_count` | The number of reblogs for the status |
  325. | `favourites_count` | The number of favourites for the status |
  326. | `reblogged` | Whether the authenticated user has reblogged the status |
  327. | `favourited` | Whether the authenticated user has favourited the status |
  328. | `sensitive` | Whether media attachments should be hidden by default |
  329. | `spoiler_text` | If not empty, warning text that should be displayed before the actual content |
  330. | `visibility` | One of: `public`, `unlisted`, `private`, `direct` |
  331. | `media_attachments` | An array of [Attachments](#attachment) |
  332. | `mentions` | An array of [Mentions](#mention) |
  333. | `tags` | An array of [Tags](#tag) |
  334. | `application` | [Application](#application) from which the status was posted |
  335. ### Tags
  336. | Attribute | Description |
  337. | ------------------------ | ----------- |
  338. | `name` | The hashtag, not including the preceding `#` |
  339. | `url` | The URL of the hashtag |