Skip to content

Latest commit

 

History

History
523 lines (339 loc) · 15.4 KB

API.md

File metadata and controls

523 lines (339 loc) · 15.4 KB
Raw

API overview

Contents

Available libraries

Notes

Parameter types

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.

Selecting ranges

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. API methods that return collections of items can return a Link header containing URLs for the next and prev pages. See the Link header RFC for more information.

Errors

If the request you make doesn't go through, Mastodon will usually respond with an Error.

Methods

Accounts

Fetching an account:

GET /api/v1/accounts/:id

Returns an Account.

Getting the current user:

GET /api/v1/accounts/verify_credentials

Returns the authenticated user's Account.

Getting an account's followers:

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

Returns an array of Accounts.

Getting who account is following:

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

Returns an array of Accounts.

Getting an account's statuses:

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

Query parameters:

  • only_media (optional): Only return statuses that have media attachments
  • exclude_replies (optional): Skip statuses that reply to other statuses

Returns an array of Statuses.

Following/unfollowing an account:

GET /api/v1/accounts/:id/follow
GET /api/v1/accounts/:id/unfollow

Returns the target Account.

Blocking/unblocking an account:

GET /api/v1/accounts/:id/block
GET /api/v1/accounts/:id/unblock

Returns the target Account.

Muting/unmuting an account:

GET /api/v1/accounts/:id/mute
GET /api/v1/accounts/:id/unmute

Returns the target Account.

Getting an account's relationships:

GET /api/v1/accounts/relationships

Query parameters:

  • id (can be array): Account IDs

Returns an array of Relationships of the current user to a list of given accounts.

Searching for accounts:

GET /api/v1/accounts/search

Query parameters:

  • q: What to search for
  • limit: Maximum number of matching accounts to return (default: 40)

Returns an array of matching Accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database.

Apps

Registering an application:

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 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.

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.

Blocks

Fetching a user's blocks:

GET /api/v1/blocks

Returns an array of Accounts blocked by the authenticated user.

Favourites

Fetching a user's favourites:

GET /api/v1/favourites

Returns an array of Statuses favourited by the authenticated user.

Follow Requests

Fetching a list of follow requests:

GET /api/v1/follow_requests

Returns an array of Accounts which have requested to follow the authenticated user.

Authorizing or rejecting follow requests:

POST /api/v1/follow_requests/authorize
POST /api/v1/follow_requests/reject

Form data:

  • id: The id of the account to authorize or reject

Returns an empty object.

Follows

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, as an Account.

Instances

Getting instance information:

GET /api/v1/instance

Returns the current Instance. Does not require authentication.

Media

Uploading a media attachment:

POST /api/v1/media

Form data:

  • file: Media to be uploaded

Returns an Attachment that can be used when creating a status.

Mutes

Fetching a user's mutes:

GET /api/v1/mutes

Returns an array of Accounts muted by the authenticated user.

Notifications

Fetching a user's notifications:

GET /api/v1/notifications

Returns a list of Notifications for the authenticated user.

Getting a single notification:

GET /api/v1/notifications/:id

Returns the Notification.

Clearing notifications:

POST /api/v1/notifications/clear

Deletes all notifications from the Mastodon server for the authenticated user. Returns an empty object.

Reports

Fetching a user's reports:

GET /api/v1/reports

Returns a list of Reports made by the authenticated user.

Reporting a user:

POST /api/v1/reports

Form data:

  • account_id: The ID of the account to report
  • status_ids: The IDs of statuses to report (can be an array)
  • comment: A comment to associate with the report.

Returns the finished Report.

Search

Searching for content:

GET /api/v1/search

Form data:

  • q: The search query
  • resolve: Whether to resolve non-local accounts

Returns Results. If q is a URL, Mastodon will attempt to fetch the provided account or status. Otherwise, it will do a local account and hashtag search.

Statuses

Fetching a status:

GET /api/v1/statuses/:id

Returns a Status.

Getting status context:

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

Returns a Context.

Getting a card associated with a status:

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

Returns a Card.

Getting who reblogged/favourited a status:

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

Returns an array of Accounts.

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
  • spoiler_text (optional): text to be shown as a warning before the actual content
  • visibility (optional): either "direct", "private", "unlisted" or "public"

Returns the new Status.

Deleting a status:

DELETE /api/v1/statuses/:id

Returns an empty object.

Reblogging/unreblogging a status:

POST /api/vi/statuses/:id/reblog
POST /api/vi/statuses/:id/unreblog

Returns the target Status.

Favouriting/unfavouriting a status:

POST /api/vi/statuses/:id/favourite
POST /api/vi/statuses/:id/unfavourite

Returns the target Status.

Timelines

Retrieving a timeline:

GET /api/v1/timelines/home
GET /api/v1/timelines/public
GET /api/v1/timelines/tag/:hashtag

Query parameters:

  • local (optional; public and tag timelines only): Only return statuses originating from this instance

Returns an array of Statuses, most recent ones first.

Entities

Account

Attribute Description
id The ID of the account
username The username of the account
acct Equals username for local users, includes @domain for remote ones
display_name The account's 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
locked Boolean for when the account cannot be followed without waiting for approval first
created_at The time the account was created
followers_count The number of followers for the account
following_count The number of accounts the given account is following
statuses_count The number of statuses the account has made

Application

Attribute Description
name Name of the app
website Homepage URL of the app

Attachment

Attribute Description
id ID of the attachment
type One of: "image", "video", "gifv"
url URL of the locally hosted version of the image
remote_url For remote images, the remote URL of the original image
preview_url URL of the preview image
text_url Shorter URL for the image, for insertion into text (only present on local images)

Card

Attribute Description
url The url associated with the card
title The title of the card
description The card description
image The image associated with the card, if any

Context

Attribute Description
ancestors The ancestors of the status in the conversation, as a list of Statuses
descendants The descendants of the status in the conversation, as a list of Statuses

Error

Attribute Description
error A textual description of the error

Instance

Attribute Description
uri URI of the current instance
title The instance's title
description A description for the instance
email An email address which can be used to contact the instance administrator

Mention

Attribute Description
url URL of user's profile (can be remote)
username The username of the account
acct Equals username for local users, includes @domain for remote ones
id Account ID

Notifications

Attribute Description
id The notification ID
type One of: "mention", "reblog", "favourite", "follow"
created_at The time the notification was created
account The Account sending the notification to the user
status The Status associated with the notification, if applicible

Relationships

Attribute Description
following Whether the user is currently following the account
followed_by Whether the user is currently being followed by the account
blocking Whether the user is currently blocking the account
muting Whether the user is currently muting the account
requested Whether the user has requested to follow the account

Report

Attribute Description
id The ID of the report
action_taken The action taken in response to the report

Results

Attribute Description
accounts An array of matched Accounts
statuses An array of matchhed Statuses
hashtags An array of matched hashtags, as strings

Status

Attribute Description
id The ID of the status
uri A Fediverse-unique resource ID
url URL to the status page (can be remote)
account The Account which posted the status
in_reply_to_id null or the ID of the status it replies to
in_reply_to_account_id null or the ID of the account it replies to
reblog null or the reblogged Status
content Body of the status; this will contain HTML (remote HTML already sanitized)
created_at The time the status was created
reblogs_count The number of reblogs for the status
favourites_count The number of favourites for the status
reblogged Whether the authenticated user has reblogged the status
favourited Whether the authenticated user has favourited the status
sensitive Whether media attachments should be hidden by default
spoiler_text If not empty, warning text that should be displayed before the actual content
visibility One of: public, unlisted, private, direct
media_attachments An array of Attachments
mentions An array of Mentions
tags An array of Tags
application Application from which the status was posted

Tags

Attribute Description
name The hashtag, not including the preceding #
url The URL of the hashtag