doc/API-Mastodon.md

   1 # Mastodon API
   2
   3 * [Home](help)
   4   * [Using the APIs](help/api)
   5
   6 ## Overview
   7
   8 Friendica provides the following endpoints defined in [the official Mastodon API reference](https://docs.joinmastodon.org/api/).
   9
  10 Authentication is the same as described in [Using the APIs](help/api#Authentication).
  11
  12 ## Clients
  13
  14 ### Supported apps
  15
  16 For supported apps please have a look at the [FAQ](help/FAQ#clients)
  17
  18 ### Unsupported apps
  19
  20 #### Android
  21
  22 - [Fedilab](https://framagit.org/tom79/fedilab) Automatically uses the legacy API, see issue: https://framagit.org/tom79/fedilab/-/issues/520
  23 - [Mammut](https://github.com/jamiesanson/Mammut) There are problems with the token request, see issue https://github.com/jamiesanson/Mammut/issues/19
  24
  25 #### iOS
  26
  27 - [Mast](https://github.com/Beesitech/Mast) Doesn't accept the entered instance name. Claims that it is invalid (Message is: "Not a valid instance (may be closed or dead)")
  28 - [Toot!](https://apps.apple.com/app/toot/id1229021451)
  29
  30 ## Entities
  31
  32 These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/entities/).
  33 With some additional extensions listed below.
  34
  35 ### Instance (Version 2) Entities
  36 Extensions to the [Mastodon Instance::V2 Entities](https://docs.joinmastodon.org/entities/Instance/)
  37 * `friendica`: Friendica specific properties of the V2 Instance including:
  38     * `version`: The Friendica version string
  39     * `codename`: The Friendica version code name
  40     * `db_version`: The database schema version number
  41
  42 Example:
  43 ```json
  44 {
  45   "domain": "friendicadevtest1.myportal.social",
  46   "title": "Friendica Social Network",
  47   "version": "2.8.0 (compatible; Friendica 2023.03-dev)",
  48   ...
  49   "friendica": {
  50     "version": "2023.03-dev",
  51     "codename": "Giant Rhubarb",
  52     "db_version": 1516
  53   }
  54 }
  55 ```
  56
  57 ### Notification Entities
  58 Extensions to the [Mastodon Notification Entities](https://docs.joinmastodon.org/entities/Notification/)
  59 * `dismissed`: whether the object has been dismissed or not
  60
  61 ### Status Entities
  62 Extensions to the [Mastodon Status Entities](https://docs.joinmastodon.org/entities/Status/)
  63 * `in_reply_to_status`: A fully populated Mastodon Status entity for the replied to status or null it is a post rather than a response
  64 * `friendica`: Friendica specific properties of a status including:
  65   * `title`: The Friendica title for a post, or empty if the status is a comment
  66   * `delivery_data`: Information about the state of federating a message from the server
  67     * `delivery_queue_count`: Total number of remote servers that the status needs to be federated to.
  68     * `delivery_queue_done`: Total number of remote servers that have successfully been federated to so far.
  69     * `delivery_queue_failed`: Total number of remote servers that have we failed to federate to so far.
  70   * `dislikes_count`: The number of dislikes that a status has accumulated according to the server.
  71   * `disliked`: Whether the API user disliked the status.
  72
  73 Example:
  74 ```json
  75 {
  76   "id": "358",
  77   "created_at": "2023-02-23T02:45:46.000Z",
  78   "in_reply_to_id": "356",
  79   "in_reply_to_status": {
  80     "id": "356",
  81     "created_at": "2023-02-23T02:45:35.000Z",
  82     "in_reply_to_id": null,
  83     "in_reply_to_status": null,
  84     "in_reply_to_account_id": null,
  85     ...
  86     "content": "A post from testuser1",
  87     ...
  88     "account": {
  89       "id": "6",
  90       "username": "testuser1",
  91       "acct": "testuser1",
  92       "display_name": "testuser1",
  93       ...
  94     },
  95     ...
  96     "friendica": {
  97       "title": "",
  98       "dislikes_count": 0
  99     }
 100   },
 101   "in_reply_to_account_id": "6",
 102   ...
 103   "replies_count": 0,
 104   "reblogs_count": 0,
 105   "favourites_count": 0,
 106   ...
 107   "content": "A reply from testuser2",
 108   ...
 109   "account": {
 110     "id": "8",
 111     "username": "testuser2",
 112     "acct": "testuser2",
 113     "display_name": "testuser2",
 114     ...
 115   },
 116   ...
 117   "friendica": {
 118     "title": "",
 119     "delivery_data": {
 120       "delivery_queue_count": 10,
 121       "delivery_queue_done": 3,
 122       "delivery_queue_failed": 0
 123     },
 124     "dislikes_count": 0
 125   }
 126 }
 127 ```
 128
 129 ## Implemented endpoints
 130
 131 - [`GET /api/v1/accounts/:id`](https://docs.joinmastodon.org/methods/accounts/#retrieve-information)
 132 - [`POST /api/v1/accounts/:id/block`](https://docs.joinmastodon.org/methods/accounts/)
 133 - [`POST /api/v1/accounts/:id/follow`](https://docs.joinmastodon.org/methods/accounts/)
 134 - [`GET /api/v1/accounts/:id/followers`](https://docs.joinmastodon.org/methods/accounts/)
 135 - [`GET /api/v1/accounts/:id/following`](https://docs.joinmastodon.org/methods/accounts/)
 136 - [`GET /api/v1/accounts/:id/lists`](https://docs.joinmastodon.org/methods/accounts/)
 137 - [`POST /api/v1/accounts/:id/mute`](https://docs.joinmastodon.org/methods/accounts/)
 138 - [`POST /api/v1/accounts/:id/note`](https://docs.joinmastodon.org/methods/accounts/)
 139 - [`GET /api/v1/accounts/:id/statuses`](https://docs.joinmastodon.org/methods/accounts/)
 140 - [`POST /api/v1/accounts/:id/unfollow`](https://docs.joinmastodon.org/methods/accounts/)
 141 - [`POST /api/v1/accounts/:id/unblock`](https://docs.joinmastodon.org/methods/accounts/)
 142 - [`POST /api/v1/accounts/:id/unmute`](https://docs.joinmastodon.org/methods/accounts/)
 143 - [`GET /api/v1/accounts/relationships`](https://docs.joinmastodon.org/methods/accounts/)
 144 - [`GET /api/v1/accounts/search`](https://docs.joinmastodon.org/methods/accounts)
 145 - [`PATCH /api/v1/accounts/update_credentials`](https://docs.joinmastodon.org/methods/accounts/#update_credentials)
 146 - [`GET /api/v1/accounts/verify_credentials`](https://docs.joinmastodon.org/methods/accounts)
 147 - [`POST /api/v1/apps`](https://docs.joinmastodon.org/methods/apps/)
 148 - [`GET /api/v1/apps/verify_credentials`](https://docs.joinmastodon.org/methods/apps/)
 149 - [`GET /api/v1/blocks`](https://docs.joinmastodon.org/methods/accounts/blocks/)
 150 - [`GET /api/v1/bookmarks`](https://docs.joinmastodon.org/methods/accounts/bookmarks/)
 151 - [`GET /api/v1/conversations`](https://docs.joinmastodon.org/methods/timelines/conversations/)
 152 - [`DELETE /api/v1/conversations/:id`](https://docs.joinmastodon.org/methods/timelines/conversations/)
 153 - [`POST /api/v1/conversations/:id/read`](https://docs.joinmastodon.org/methods/timelines/conversations/)
 154 - [`GET /api/v1/custom_emojis`](https://docs.joinmastodon.org/methods/instance/custom_emojis/)
 155     - Doesn't return unicode emojis since they aren't using an image URL
 156
 157
 158 - [`GET /api/v1/directory`](https://docs.joinmastodon.org/methods/instance/directory/)
 159 - [`GET /api/v1/favourites`](https://docs.joinmastodon.org/methods/accounts/favourites/)
 160 - [`GET /api/v1/follow_requests`](https://docs.joinmastodon.org/methods/accounts/follow_requests#pending-follows)
 161     - Returned IDs are specific to follow requests
 162 - [`POST /api/v1/follow_requests/:id/authorize`](https://docs.joinmastodon.org/methods/accounts/follow_requests#accept-follow)
 163     - `:id` is a follow request ID, not a regular account id
 164 - [`POST /api/v1/follow_requests/:id/reject`](https://docs.joinmastodon.org/methods/accounts/follow_requests#reject-follow)
 165     - `:id` is a follow request ID, not a regular account id
 166 - `POST /api/v1/follow_requests/:id/ignore`
 167     - Friendica-specific, hides the follow request from the list and prevents the remote contact from retrying.
 168     - `:id` is a follow request ID, not a regular account id
 169     - Returns a [Relationship](https://docs.joinmastodon.org/entities/relationship) object.
 170
 171 - [`GET /api/v1/followed_tags`](https://docs.joinmastodon.org/methods/followed_tags/)
 172 - [`GET /api/v1/instance`](https://docs.joinmastodon.org/methods/instance/#v1)
 173 - `GET /api/v1/instance/rules` Undocumented, returns Terms of Service
 174 - [`GET /api/v1/instance/peers`](https://docs.joinmastodon.org/methods/instance#list-of-connected-domains)
 175 - [`GET /api/v1/lists`](https://docs.joinmastodon.org/methods/timelines/lists/)
 176 - [`POST /api/v1/lists`](https://docs.joinmastodon.org/methods/timelines/lists/)
 177 - [`GET /api/v1/lists/:id`](https://docs.joinmastodon.org/methods/timelines/lists/)
 178 - [`PUT /api/v1/lists/:id`](https://docs.joinmastodon.org/methods/timelines/lists/)
 179 - [`DELETE /api/v1/lists/:id`](https://docs.joinmastodon.org/methods/timelines/lists/)
 180 - [`GET /api/v1/lists/:id/accounts`](https://docs.joinmastodon.org/methods/timelines/lists/)
 181 - [`POST /api/v1/lists/:id/accounts`](https://docs.joinmastodon.org/methods/timelines/lists/)
 182 - [`DELETE /api/v1/lists/:id/accounts`](https://docs.joinmastodon.org/methods/timelines/lists/)
 183 - [`POST /api/v1/markers`](https://docs.joinmastodon.org/methods/timelines/markers/)
 184 - [`GET /api/v1/markers`](https://docs.joinmastodon.org/methods/timelines/markers/)
 185 - [`POST /api/v1/media`](https://docs.joinmastodon.org/methods/statuses/media/)
 186 - [`GET /api/v1/media/:id`](https://docs.joinmastodon.org/methods/statuses/media/)
 187 - [`PUT /api/v1/media/:id`](https://docs.joinmastodon.org/methods/statuses/media/)
 188 - [`GET /api/v1/mutes`](https://docs.joinmastodon.org/methods/accounts/mutes/)
 189 - [`GET /api/v1/notifications`](https://docs.joinmastodon.org/methods/notifications/)
 190     - Additional field `include_all` to return read and unread statuses, defaults to `false`
 191     - Additional field `summary` returns a count of all of the statuses that match the type filter
 192     - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
 193     - Does not support the `type` field, which is the mirror image of the supported `exclude_types` field
 194 - [`GET /api/v1/notifications/:id`](https://docs.joinmastodon.org/methods/notifications/)
 195 - [`POST /api/v1/notifications/clear`](https://docs.joinmastodon.org/methods/notifications/)
 196 - [`POST /api/v1/notifications/:id/dismiss`](https://docs.joinmastodon.org/methods/notifications/)
 197 - [`GET /api/v1/polls/:id`](https://docs.joinmastodon.org/methods/statuses/polls/)
 198 - [`GET /api/v1/preferences`](https://docs.joinmastodon.org/methods/accounts/preferences/)
 199 - [`DELETE /api/v1/push/subscription`](https://docs.joinmastodon.org/methods/notifications/push/)
 200 - [`GET /api/v1/push/subscription`](https://docs.joinmastodon.org/methods/notifications/push/)
 201 - [`PUSH /api/v1/push/subscription`](https://docs.joinmastodon.org/methods/notifications/push/)
 202 - [`PUT /api/v1/push/subscription`](https://docs.joinmastodon.org/methods/notifications/push/)
 203 - [`POST /api/v1/reports`](https://docs.joinmastodon.org/methods/accounts/reports/)
 204 - [`GET /api/v1/scheduled_statuses`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 205 - [`DELETE /api/v1/scheduled_statuses/:id`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 206 - [`GET /api/v1/scheduled_statuses/:id`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 207 - [`GET /api/v1/search`](https://docs.joinmastodon.org/methods/search/)
 208 - [`PUT /api/v1/statuses`](https://docs.joinmastodon.org/methods/statuses/#edit)
 209     - Does not support `polls` argument as Friendica does not have polls
 210     - Additional fields `friendica` for Friendica specific parameters:
 211         - `title`: Explicitly sets the title for a post status, ignored if used on a comment status. For post statuses the legacy behavior is to use any "spoiler text" as the title if it is provided. If both the title and spoiler text are provided for a post status then they will each be used for their respective roles. If no title is provided then the legacy behavior will persist. If you want to create a post with no title but spoiler text then explicitly set the title but set it to an empty string `""`.
 212 - [`POST /api/v1/statuses`](https://docs.joinmastodon.org/methods/statuses/#create)
 213     - Does not support `polls` argument as Friendica does not have polls
 214     - Additionally to the static values `public`, `unlisted` and `private`, the `visibility` parameter can contain a numeric value with a circle id.
 215     - Additional field `quote_id` for the post that is being quote reshared
 216     - Additional fields `friendica` for Friendica specific parameters:
 217        - `title`: Explicitly sets the title for a post status, ignored if used on a comment status. For post statuses the legacy behavior is to use any "spoiler text" as the title if it is provided. If both the title and spoiler text are provided for a post status then they will each be used for their respective roles. If no title is provided then the legacy behavior will persist. If you want to create a post with no title but spoiler text then explicitly set the title but set it to an empty string `""`.
 218 - [`GET /api/v1/statuses/:id`](https://docs.joinmastodon.org/methods/statuses/#get)
 219 - [`DELETE /api/v1/statuses/:id`](https://docs.joinmastodon.org/methods/statuses/#delete)
 220 - [`GET /api/v1/statuses/:id/context`](https://docs.joinmastodon.org/methods/statuses/#context)
 221     - Additional support for paging using `min_id`, `max_id`, `since_id` parameters
 222     - Additional support for previous/next Link Headers to support paging
 223     - Additional flag `show_all` to allow including posts from blocked and ignored/muted users, defaults to `false`
 224 - [`GET /api/v1/statuses/:id/reblogged_by`](https://docs.joinmastodon.org/methods/statuses/#reblogged_by)
 225 - [`GET /api/v1/statuses/:id/favourited_by`](https://docs.joinmastodon.org/methods/statuses/#favourited_by)
 226 - [`POST /api/v1/statuses/:id/favourite`](https://docs.joinmastodon.org/methods/statuses/#favourite)
 227 - [`POST /api/v1/statuses/:id/unfavourite`](https://docs.joinmastodon.org/methods/statuses/#unfavourite)
 228 - [`POST /api/v1/statuses/:id/reblog`](https://docs.joinmastodon.org/methods/statuses/#boost)
 229 - [`POST /api/v1/statuses/:id/unreblog`](https://docs.joinmastodon.org/methods/statuses/#unreblog)
 230 - [`POST /api/v1/statuses/:id/bookmark`](https://docs.joinmastodon.org/methods/statuses/#bookmark)
 231 - [`POST /api/v1/statuses/:id/unbookmark`](https://docs.joinmastodon.org/methods/statuses/#unbookmark)
 232 - [`POST /api/v1/statuses/:id/mute`](https://docs.joinmastodon.org/methods/statuses/#mute)
 233 - [`POST /api/v1/statuses/:id/unmute`](https://docs.joinmastodon.org/methods/statuses/#unmute)
 234 - [`POST /api/v1/statuses/:id/pin`](https://docs.joinmastodon.org/methods/statuses/#pin)
 235 - [`POST /api/v1/statuses/:id/unpin`](https://docs.joinmastodon.org/methods/statuses/#unpin)
 236 - [`POST /api/v1/statuses/:id`](https://docs.joinmastodon.org/methods/statuses/#edit)
 237 - [`GET /api/v1/statuses/:id/source`](https://docs.joinmastodon.org/methods/statuses/#source)
 238 - [`GET /api/v1/statuses/:id/card`](https://docs.joinmastodon.org/methods/statuses/#card)
 239 - [`GET /api/v1/suggestions`](https://docs.joinmastodon.org/methods/accounts/suggestions/)
 240 - [`GET /api/v1/tags/:id`](https://docs.joinmastodon.org/methods/tags/#get)
 241 - [`GET /api/v1/tags/:id/follow`](https://docs.joinmastodon.org/methods/tags/#follow)
 242 - [`GET /api/v1/tags/:id/unfollow`](https://docs.joinmastodon.org/methods/tags/#unfollow)
 243 - [`GET /api/v1/timelines/direct`](https://docs.joinmastodon.org/methods/timelines/)
 244 - [`GET /api/v1/timelines/home`](https://docs.joinmastodon.org/methods/timelines/)
 245     - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
 246     - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 247 - [`GET /api/v1/timelines/list/:id`](https://docs.joinmastodon.org/methods/timelines/)
 248     - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
 249     - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 250 - [`GET /api/v1/timelines/public`](https://docs.joinmastodon.org/methods/timelines/)
 251     - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
 252     - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 253 - [`GET /api/v1/timelines/tag/:hashtag`](https://docs.joinmastodon.org/methods/timelines/)
 254     - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
 255     - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 256     - Does not support the `any[]`, `all[]`, or `none[]` query parameters
 257 - [`GET /api/v1/trends`](https://docs.joinmastodon.org/methods/instance/trends/)
 258 - [`GET /api/v1/trends/links`](https://github.com/mastodon/mastodon/pull/16917)
 259 - [`GET /api/v1/trends/statuses`](https://docs.joinmastodon.org/methods/trends/#statuses)
 260 - [`GET /api/v1/trends/tags`](https://docs.joinmastodon.org/methods/trends/#tags)
 261     - Additional field `friendica_local` to return local trending tags instead of global tags, defaults to `false`
 262 - [`GET /api/v2/instance`](https://docs.joinmastodon.org/methods/instance/#v2)
 263 - [`GET /api/v2/search`](https://docs.joinmastodon.org/methods/search/)
 264
 265
 266 ## Currently unimplemented endpoints
 267
 268 These endpoints are planned to be implemented somewhere in the future.
 269
 270 - [`POST /api/v1/accounts/:id/remove_from_followers`](https://github.com/mastodon/mastodon/pull/16864)
 271 - [`GET /api/v1/accounts/familiar_followers`](https://github.com/mastodon/mastodon/pull/17700)
 272 - [`GET /api/v1/accounts/lookup`](https://github.com/mastodon/mastodon/pull/15740)
 273 - [`POST /api/v1/polls/:id/votes`](https://docs.joinmastodon.org/methods/statuses/polls/)
 274 - [`GET /api/v1/featured_tags`](https://docs.joinmastodon.org/methods/accounts/featured_tags/)
 275 - [`POST /api/v1/featured_tags`](https://docs.joinmastodon.org/methods/accounts/featured_tags/)
 276 - [`DELETE /api/v1/featured_tags/:id`](https://docs.joinmastodon.org/methods/accounts/featured_tags/)
 277
 278 ## Dummy endpoints
 279
 280 These endpoints are returning empty data to avoid error messages when using third party clients.
 281 They refer to features that don't exist in Friendica yet.
 282
 283 - [`GET /api/v1/accounts/:id/identity_proofs`](https://docs.joinmastodon.org/methods/accounts/)
 284 - [`GET /api/v1/announcements`](https://docs.joinmastodon.org/methods/announcements/)
 285 - [`GET /api/v1/endorsements`](https://docs.joinmastodon.org/methods/accounts/endorsements/)
 286 - [`GET /api/v1/filters`](https://docs.joinmastodon.org/methods/accounts/filters/)
 287
 288 ## Non supportable endpoints
 289
 290 These endpoints won't be implemented at the moment.
 291 They refer to features or data that don't exist in Friendica yet.
 292
 293 - `POST /api/meta` Misskey API endpoint.
 294 - [`POST /api/v1/accounts`](https://docs.joinmastodon.org/methods/accounts/)
 295 - [`GET /api/v1/accounts/:id/featured_tags`](https://docs.joinmastodon.org/methods/accounts/)
 296 - [`POST /api/v1/accounts/:id/pin`](https://docs.joinmastodon.org/methods/accounts/)
 297 - [`POST /api/v1/accounts/:id/unpin`](https://docs.joinmastodon.org/methods/accounts/)
 298 - [`GET /api/v1/admin/accounts`](https://docs.joinmastodon.org/methods/admin/)
 299 - [`GET /api/v1/admin/accounts/:id`](https://docs.joinmastodon.org/methods/admin/)
 300 - [`POST /api/v1/admin/accounts/:id/{action}`](https://docs.joinmastodon.org/methods/admin/)
 301 - [`GET /api/v1/admin/reports`](https://docs.joinmastodon.org/methods/admin/)
 302 - [`GET /api/v1/admin/reports/:id`](https://docs.joinmastodon.org/methods/admin/)
 303 - [`POST /api/v1/admin/reports/:id/{action}`](https://docs.joinmastodon.org/methods/admin/)
 304 - [`POST /api/v1/announcements/:id/dismiss`](https://docs.joinmastodon.org/methods/announcements/)
 305 - [`PUT /api/v1/announcements/:id/reactions/{name}`](https://docs.joinmastodon.org/methods/announcements/)
 306 - [`DELETE /api/v1/announcements/:id/reactions/{name}`](https://docs.joinmastodon.org/methods/announcements/)
 307 - [`GET /api/v1/domain_blocks`](https://docs.joinmastodon.org/methods/accounts/domain_blocks/)
 308 - [`POST /api/v1/domain_blocks`](https://docs.joinmastodon.org/methods/accounts/domain_blocks/)
 309 - [`DELETE /api/v1/domain_blocks`](https://docs.joinmastodon.org/methods/accounts/domain_blocks/)
 310 - [`DELETE /api/v1/emails/confirmations`](https://github.com/mastodon/mastodon/pull/15816)
 311 - [`GET /api/v1/featured_tags/suggestions`](https://docs.joinmastodon.org/methods/accounts/featured_tags/)
 312 - [`GET /api/v1/filters/:id`](https://docs.joinmastodon.org/methods/accounts/filters/)
 313 - [`POST /api/v1/filters/:id`](https://docs.joinmastodon.org/methods/accounts/filters/)
 314 - [`PUT /api/v1/filters/:id`](https://docs.joinmastodon.org/methods/accounts/filters/)
 315 - [`DELETE /api/v1/filters/:id`](https://docs.joinmastodon.org/methods/accounts/filters/)
 316 - [`GET /api/v1/instance/activity`](https://docs.joinmastodon.org/methods/instance#weekly-activity)
 317 - [`POST /api/v1/markers`](https://docs.joinmastodon.org/methods/timelines/markers/)
 318 - [`PUT /api/v1/scheduled_statuses/:id`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 319 - [`GET /api/v1/statuses/{id:\d+}/history`](https://github.com/mastodon/mastodon/pull/16697)
 320 - [`GET /api/v1/streaming`](https://docs.joinmastodon.org/methods/timelines/streaming/)
 321 - [`DELETE /api/v1/suggestions/:id`](https://docs.joinmastodon.org/methods/accounts/suggestions/)