friendica-github/doc/API-Mastodon.md

Mastodon API

• Home
  • Using the APIs

Overview

Friendica provides the following endpoints defined in the official Mastodon API reference.

Authentication is the same as described in Using the APIs.

Clients

Please find a list of supported apps at FAQ.

Entities

These endpoints use the Mastodon API entities. With some additional extensions listed below.

Instance (Version 2) Entities

Extensions to the Mastodon Instance::V2 Entities

• friendica: Friendica specific properties of the V2 Instance including:
  • version: The Friendica version string
  • codename: The Friendica version code name
  • db_version: The database schema version number

Example:

{
  "domain": "friendicadevtest1.myportal.social",
  "title": "Friendica Social Network",
  "version": "2.8.0 (compatible; Friendica 2023.03-dev)",
  ...
  "friendica": {
    "version": "2023.03-dev",
    "codename": "Giant Rhubarb",
    "db_version": 1516
  }
}

Notification Entities

Extensions to the Mastodon Notification Entities

• dismissed: whether the object has been dismissed or not

Status Entities

Extensions to the Mastodon Status Entities

• 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
• friendica: Friendica specific properties of a status including:
  • title: The Friendica title for a post, or empty if the status is a comment
  • delivery_data: Information about the state of federating a message from the server
    • delivery_queue_count: Total number of remote servers that the status needs to be federated to.
    • delivery_queue_done: Total number of remote servers that have successfully been federated to so far.
    • delivery_queue_failed: Total number of remote servers that have we failed to federate to so far.
  • dislikes_count: The number of dislikes that a status has accumulated according to the server.
  • disliked: Whether the API user disliked the status.

Example:

{
  "id": "358",
  "created_at": "2023-02-23T02:45:46.000Z",
  "in_reply_to_id": "356",
  "in_reply_to_status": {
    "id": "356",
    "created_at": "2023-02-23T02:45:35.000Z",
    "in_reply_to_id": null,
    "in_reply_to_status": null,
    "in_reply_to_account_id": null,
    ...
    "content": "A post from testuser1",
    ...
    "account": {
      "id": "6",
      "username": "testuser1",
      "acct": "testuser1",
      "display_name": "testuser1",
      ...
    },
    ...
    "friendica": {
      "title": "",
      "dislikes_count": 0
    }
  },
  "in_reply_to_account_id": "6",
  ...
  "replies_count": 0,
  "reblogs_count": 0,
  "favourites_count": 0,
  ...
  "content": "A reply from testuser2",
  ...
  "account": {
    "id": "8",
    "username": "testuser2",
    "acct": "testuser2",
    "display_name": "testuser2",
    ...
  },
  ...
  "friendica": {
    "title": "",
    "delivery_data": {
      "delivery_queue_count": 10,
      "delivery_queue_done": 3,
      "delivery_queue_failed": 0
    },
    "dislikes_count": 0
  }
}

Implemented endpoints

• GET /api/v1/accounts/:id

• POST /api/v1/accounts/:id/block

• POST /api/v1/accounts/:id/follow

• GET /api/v1/accounts/:id/followers

• GET /api/v1/accounts/:id/following

• GET /api/v1/accounts/:id/lists

• POST /api/v1/accounts/:id/mute

• POST /api/v1/accounts/:id/note

• GET /api/v1/accounts/:id/statuses

• POST /api/v1/accounts/:id/unfollow

• POST /api/v1/accounts/:id/unblock

• POST /api/v1/accounts/:id/unmute

• GET /api/v1/accounts/relationships

• GET /api/v1/accounts/search

• PATCH /api/v1/accounts/update_credentials

• GET /api/v1/accounts/verify_credentials

• POST /api/v1/apps

• GET /api/v1/apps/verify_credentials

• GET /api/v1/blocks

• GET /api/v1/bookmarks

• GET /api/v1/conversations

• DELETE /api/v1/conversations/:id

• POST /api/v1/conversations/:id/read

• GET /api/v1/custom_emojis

  • Doesn't return unicode emojis since they aren't using an image URL

• GET /api/v1/directory

• GET /api/v1/favourites

• GET /api/v1/follow_requests

  • Returned IDs are specific to follow requests

• POST /api/v1/follow_requests/:id/authorize

  • :id is a follow request ID, not a regular account id

• POST /api/v1/follow_requests/:id/reject

  • :id is a follow request ID, not a regular account id

• POST /api/v1/follow_requests/:id/ignore

  • Friendica-specific, hides the follow request from the list and prevents the remote contact from retrying.
  • :id is a follow request ID, not a regular account id
  • Returns a Relationship object.

• GET /api/v1/followed_tags

• GET /api/v1/instance

• GET /api/v1/instance/extended_description

• GET /api/v1/instance/rules

• GET /api/v1/instance/peers

• GET /api/v1/lists

• POST /api/v1/lists

• GET /api/v1/lists/:id

• PUT /api/v1/lists/:id

• DELETE /api/v1/lists/:id

• GET /api/v1/lists/:id/accounts

• POST /api/v1/lists/:id/accounts

• DELETE /api/v1/lists/:id/accounts

• POST /api/v1/markers

• GET /api/v1/markers

• POST /api/v1/media

• GET /api/v1/media/:id

• PUT /api/v1/media/:id

• GET /api/v1/mutes

• GET /api/v1/notifications

  • Additional field include_all to return read and unread statuses, defaults to false
  • Additional field summary returns a count of all of the statuses that match the type filter
  • Additional field with_muted Pleroma extension to return notifications from muted users, defaults to false
  • Does not support the type field, which is the mirror image of the supported exclude_types field

• GET /api/v1/notifications/:id

• POST /api/v1/notifications/clear

• POST /api/v1/notifications/:id/dismiss

• GET /api/v1/polls/:id

• GET /api/v1/preferences

• DELETE /api/v1/push/subscription

• GET /api/v1/push/subscription

• PUSH /api/v1/push/subscription

• PUT /api/v1/push/subscription

• POST /api/v1/reports

• GET /api/v1/scheduled_statuses

• DELETE /api/v1/scheduled_statuses/:id

• GET /api/v1/scheduled_statuses/:id

• GET /api/v1/search

• PUT /api/v1/statuses

  • Does not support polls argument as Friendica does not have polls
  • Additional fields friendica for Friendica specific parameters:
    • 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 "".

• POST /api/v1/statuses

  • Does not support polls argument as Friendica does not have polls
  • Additionally to the static values public, unlisted and private, the visibility parameter can contain a numeric value with a circle id.
  • Additional field quote_id for the post that is being quote reshared
  • Additional fields friendica for Friendica specific parameters:
    • 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 "".

• GET /api/v1/statuses/:id

• DELETE /api/v1/statuses/:id

• GET /api/v1/statuses/:id/context

  • Additional support for paging using min_id, max_id, since_id parameters
  • Additional support for previous/next Link Headers to support paging
  • Additional flag show_all to allow including posts from blocked and ignored/muted users, defaults to false

• GET /api/v1/statuses/:id/reblogged_by

• GET /api/v1/statuses/:id/favourited_by

• POST /api/v1/statuses/:id/favourite

• POST /api/v1/statuses/:id/unfavourite

• POST /api/v1/statuses/:id/reblog

• POST /api/v1/statuses/:id/unreblog

• POST /api/v1/statuses/:id/bookmark

• POST /api/v1/statuses/:id/unbookmark

• POST /api/v1/statuses/:id/mute

• POST /api/v1/statuses/:id/unmute

• POST /api/v1/statuses/:id/pin

• POST /api/v1/statuses/:id/unpin

• POST /api/v1/statuses/:id

• GET /api/v1/statuses/:id/source

• GET /api/v1/statuses/:id/card

• GET /api/v1/suggestions

• GET /api/v1/tags/:id

• GET /api/v1/tags/:id/follow

• GET /api/v1/tags/:id/unfollow

• GET /api/v1/timelines/direct

• GET /api/v1/timelines/home

  • Additional field with_muted Pleroma extension to return notifications from muted users, defaults to false
  • Additional field exclude_replies to only return post statuses not replies/comments, defaults to false

• GET /api/v1/timelines/list/:id

  • Additional field with_muted Pleroma extension to return notifications from muted users, defaults to false
  • Additional field exclude_replies to only return post statuses not replies/comments, defaults to false

• GET /api/v1/timelines/public

  • Additional field with_muted Pleroma extension to return notifications from muted users, defaults to false
  • Additional field exclude_replies to only return post statuses not replies/comments, defaults to false

• GET /api/v1/timelines/tag/:hashtag

  • Additional field with_muted Pleroma extension to return notifications from muted users, defaults to false
  • Additional field exclude_replies to only return post statuses not replies/comments, defaults to false
  • Does not support the any[], all[], or none[] query parameters

• GET /api/v1/trends

• GET /api/v1/trends/links

• GET /api/v1/trends/statuses

• GET /api/v1/trends/tags

  • Additional field friendica_local to return local trending tags instead of global tags, defaults to false

• GET /api/v2/instance

• GET /api/v2/search

Currently unimplemented endpoints

These endpoints are planned to be implemented somewhere in the future.

• POST /api/v1/accounts/:id/remove_from_followers
• GET /api/v1/accounts/familiar_followers
• GET /api/v1/accounts/lookup
• POST /api/v1/polls/:id/votes
• GET /api/v1/featured_tags
• POST /api/v1/featured_tags
• DELETE /api/v1/featured_tags/:id

Dummy endpoints

These endpoints are returning empty data to avoid error messages when using third party clients. They refer to features that don't exist in Friendica yet.

• GET /api/v1/accounts/:id/identity_proofs
• GET /api/v1/announcements
• GET /api/v1/endorsements
• GET /api/v1/filters

Non supportable endpoints

These endpoints won't be implemented at the moment. They refer to features or data that don't exist in Friendica yet.

• POST /api/meta Misskey API endpoint.
• POST /api/v1/accounts
• GET /api/v1/accounts/:id/featured_tags
• POST /api/v1/accounts/:id/pin
• POST /api/v1/accounts/:id/unpin
• GET /api/v1/admin/accounts
• GET /api/v1/admin/accounts/:id
• POST /api/v1/admin/accounts/:id/{action}
• GET /api/v1/admin/reports
• GET /api/v1/admin/reports/:id
• POST /api/v1/admin/reports/:id/{action}
• POST /api/v1/announcements/:id/dismiss
• PUT /api/v1/announcements/:id/reactions/{name}
• DELETE /api/v1/announcements/:id/reactions/{name}
• GET /api/v1/domain_blocks
• POST /api/v1/domain_blocks
• DELETE /api/v1/domain_blocks
• DELETE /api/v1/emails/confirmations
• GET /api/v1/featured_tags/suggestions
• GET /api/v1/filters/:id
• POST /api/v1/filters/:id
• PUT /api/v1/filters/:id
• DELETE /api/v1/filters/:id
• GET /api/v1/instance/activity
• PUT /api/v1/scheduled_statuses/:id
• GET /api/v1/statuses/{id:\d+}/history
• GET /api/v1/streaming
• DELETE /api/v1/suggestions/:id