1
2
3
4
5
6
7
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
API overview
============
## Contents
- [Available libraries](#available-libraries)
- [Notes](#notes)
- [Methods](#methods)
- Posting a status
- Uploading media
- Retrieving a timeline
- Retrieving notifications
- Following a remote user
- Fetching data
- Deleting a status
- Reblogging a status
- Favouriting a status
- Threads (status context)
- Who reblogged/favourited a status
- Following/unfollowing accounts
- Blocking/unblocking accounts
- Creating OAuth apps
- [Entities](#entities)
- Status
- Account
- [Pagination](#pagination)
## Available libraries
- [For Ruby](https://github.com/tootsuite/mastodon-api)
- [For Python](https://github.com/halcy/Mastodon.py)
- [For JavaScript](https://github.com/Zatnosk/libodonjs)
- [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon)
## Notes
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.
When a file parameter is mentioned, a form-encoded upload is expected.
## Methods
### Posting a new status
**POST /api/v1/statuses**
Form data:
- `status`: The text of the status
- `in_reply_to_id` (optional): local ID of the status you want to reply to
- `media_ids` (optional): array of media IDs to attach to the status (maximum 4)
- `sensitive` (optional): set this to mark the media of the status as NSFW
- `visibility` (optional): either `private`, `unlisted` or `public`
Returns the new status.
**POST /api/v1/media**
Form data:
- `file`: Image to be uploaded
Returns a media object with an ID that can be attached when creating a status (see above).
### Retrieving a timeline
**GET /api/v1/timelines/home**
**GET /api/v1/timelines/mentions**
**GET /api/v1/timelines/public**
**GET /api/v1/timelines/tag/:hashtag**
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.
Query parameters:
- `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time)
- `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
### Notifications
**GET /api/v1/notifications**
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`.
### Following a remote user
**POST /api/v1/follows**
Form data:
- uri: username@domain of the person you want to follow
Returns the local representation of the followed account.
### Fetching data
**GET /api/v1/statuses/:id**
Returns status.
**GET /api/v1/accounts/:id**
Returns account.
**GET /api/v1/accounts/verify_credentials**
Returns authenticated user's account.
**GET /api/v1/accounts/:id/statuses**
Returns statuses by user. Same options as timeline are permitted.
**GET /api/v1/accounts/:id/following**
Returns users the given user is following.
**GET /api/v1/accounts/:id/followers**
Returns users the given user is followed by.
**GET /api/v1/accounts/relationships**
Returns relationships (`following`, `followed_by`, `blocking`) of the current user to a list of given accounts.
Query parameters:
- `id` (can be array): Account IDs
**GET /api/v1/accounts/search**
Returns matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database.
Query parameters:
- `q`: what to search for
- `limit`: maximum number of matching accounts to return
**GET /api/v1/blocks**
Returns accounts blocked by authenticated user.
**GET /api/v1/favourites**
Returns statuses favourited by authenticated user.
### Deleting a status
**DELETE /api/v1/statuses/:id**
Returns an empty object.
### Reblogging a status
**POST /api/v1/statuses/:id/reblog**
Returns a new status that wraps around the reblogged one.
### Unreblogging a status
**POST /api/v1/statuses/:id/unreblog**
Returns the status that used to be reblogged.
### Favouriting a status
**POST /api/v1/statuses/:id/favourite**
Returns the target status.
### Unfavouriting a status
**POST /api/v1/statuses/:id/unfavourite**
Returns the target status.
### Threads
**GET /api/v1/statuses/:id/context**
Returns `ancestors` and `descendants` of the status.
### Who reblogged/favourited a status
**GET /api/v1/statuses/:id/reblogged_by**
**GET /api/v1/statuses/:id/favourited_by**
Returns list of accounts.
### Following and unfollowing users
**POST /api/v1/accounts/:id/follow**
**POST /api/v1/accounts/:id/unfollow**
Returns the updated relationship to the user.
### Blocking and unblocking users
**POST /api/v1/accounts/:id/block**
**POST /api/v1/accounts/:id/unblock**
Returns the updated relationship to the user.
### OAuth apps
**POST /api/v1/apps**
Form data:
- `client_name`: Name of your application
- `redirect_uris`: Where the user should be redirected after authorization (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`)
- `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)
- `website`: (optional) URL to the homepage of your app
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).
___
## Entities
### Status
| Attribute | Description |
|---------------------|-------------|
| `id` ||
| `uri` | fediverse-unique resource ID |
| `url` | URL to the status page (can be remote) |
| `account` | Account |
| `in_reply_to_id` | null or ID of status it replies to |
| `reblog` | null or Status|
| `content` | Body of the status. This will contain HTML (remote HTML already sanitized) |
| `created_at` ||
| `reblogs_count` ||
| `favourites_count` ||
| `reblogged` | Boolean for authenticated user |
| `favourited` | Boolean for authenticated user |
| `media_attachments` | array of MediaAttachments |
| `mentions` | array of Mentions |
| `application` | Application from which the status was posted |
Media Attachment:
| Attribute | Description |
|---------------------|-------------|
| `url` | URL of the original image (can be remote) |
| `preview_url` | URL of the preview image |
| `type` | Image or video |
Mention:
| Attribute | Description |
|---------------------|-------------|
| `url` | URL of user's profile (can be remote) |
| `acct` | Username for local or username@domain for remote users |
| `id` | Account ID |
Application:
| Attribute | Description |
|---------------------|-------------|
| `name` | Name of the app |
| `website` | Homepage URL of the app |
### Account
| Attribute | Description |
|-------------------|-------------|
| `id` ||
| `username` ||
| `acct` | Equals username for local users, includes @domain for remote ones |
| `display_name` ||
| `note` | Biography of user |
| `url` | URL of the user's profile page (can be remote) |
| `avatar` | URL to the avatar image |
| `header` | URL to the header image |
| `followers_count` ||
| `following_count` ||
| `statuses_count` ||
## Pagination
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)
|
