API.md

API overview

Contents

• Available libraries
• Notes
• 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
  • Getting instance information
  • Creating OAuth apps
• Entities
  • Status
  • Account
• Pagination

Available libraries

• For Ruby
• For Python
• For JavaScript
• For JavaScript (Node.js)

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
• spoiler_text (optional): text to be shown as a warning before the actual content

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/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)

Query parameters for public and tag timelines only:

• local (optional): Only return statuses originating from this instance

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.

GET /api/v1/notifications/:id

Returns single notification.

POST /api/v1/notifications/clear

Clears all of user's notifications.

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.

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)
• only_media (optional): Only return statuses that have media attachments
• exclude_replies (optional): Skip statuses that reply to other statuses

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, muting, requested) 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/mutes

Returns accounts muted by authenticated user.

GET /api/v1/follow_requests

Returns accounts that want to follow the authenticated user but are waiting for approval.

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.