API Routes Reference

View Source

Bonfire provides a Mastodon-compatible REST API, allowing you to use existing Mastodon clients and tools.

OpenAPI Specification

OpenAPI specifications are available for client generation and tooling:

Coverage Summary

StatusCountPercentage
Implemented5323.6%
Not implemented16071.1%
Errors/Issues125.3%
Total225100%

Implemented Endpoints

The following endpoints are currently implemented and working:

Instance & Discovery

MethodEndpointDescription
GET/.well-known/host-metaHost metadata (WebFinger)
GET/.well-known/nodeinfoNodeInfo discovery
GET/.well-known/webfingerWebFinger lookup
GET/nodeinfo/{version}NodeInfo details
GET/api/v1/instanceInstance information
GET/api/v2/instanceInstance information (v2)
GET/api/v1/custom_emojisCustom emoji list

Authentication & Accounts

MethodEndpointDescription
GET/api/v1/accounts/verify_credentialsVerify access token
GET/api/v1/accounts/relationshipsGet relationships with accounts
GET/api/v1/accounts/{id}Get account by ID
GET/api/v1/accounts/{id}/followersGet account's followers
GET/api/v1/accounts/{id}/followingGet accounts followed by account
GET/api/v1/accounts/{id}/statusesGet account's statuses
POST/api/v1/accounts/{id}/muteMute an account
POST/api/v1/accounts/{id}/unfollowUnfollow an account
GET/api/v1/preferencesGet user preferences

Timelines

MethodEndpointDescription
GET/api/v1/timelines/homeHome timeline
GET/api/v1/timelines/publicPublic/federated timeline
GET/api/v1/timelines/list/{id}List timeline
GET/api/v1/timelines/tag/{tag}Hashtag timeline

Statuses

MethodEndpointDescription
POST/api/v1/statusesCreate a status
GET/api/v1/statuses/{id}Get a status
DELETE/api/v1/statuses/{id}Delete a status
GET/api/v1/statuses/{id}/contextGet status context (thread)
POST/api/v1/statuses/{id}/favouriteFavourite a status
POST/api/v1/statuses/{id}/unfavouriteUnfavourite a status
GET/api/v1/statuses/{id}/favourited_byGet accounts who favourited
POST/api/v1/statuses/{id}/reblogReblog/boost a status
POST/api/v1/statuses/{id}/unreblogUnreblog/unboost a status
GET/api/v1/statuses/{id}/reblogged_byGet accounts who reblogged
POST/api/v1/statuses/{id}/unbookmarkRemove status from bookmarks

Lists

MethodEndpointDescription
GET/api/v1/listsGet all lists
POST/api/v1/listsCreate a list
GET/api/v1/lists/{id}Get a list
PUT/api/v1/lists/{id}Update a list
POST/api/v1/lists/{id}/accountsAdd accounts to list
DELETE/api/v1/lists/{id}/accountsRemove accounts from list

Media

MethodEndpointDescription
GET/api/v1/media/{id}Get media attachment
PUT/api/v1/media/{id}Update media attachment

Notifications

MethodEndpointDescription
GET/api/v1/notificationsGet notifications
POST/api/v1/notifications/clearClear all notifications

Social Features

MethodEndpointDescription
GET/api/v1/bookmarksGet bookmarked statuses
GET/api/v1/favouritesGet favourited statuses
GET/api/v1/conversationsGet conversations (DMs)
GET/api/v1/mutesGet muted accounts
GET/api/v1/blocksGet blocked accounts

Follow Requests

MethodEndpointDescription
GET/api/v1/follow_requestsGet pending follow requests
GET/api/v1/follow_requests/outgoingGet outgoing requests
POST/api/v1/follow_requests/{id}/authorizeAccept follow request
POST/api/v1/follow_requests/{id}/rejectReject follow request

Reports

MethodEndpointDescription
GET/api/v1/reportsGet submitted reports
POST/api/v1/reportsCreate a report
GET/api/v1/reports/{id}Get a specific report

Not Yet Implemented

The following categories have partial or no implementation yet:

Coming Soon

  • Search (/api/v1/search, /api/v2/search) - Account and status search
  • Filters (/api/v1/filters, /api/v2/filters) - Content filtering
  • Polls (/api/v1/polls) - Poll creation and voting
  • Scheduled Statuses (/api/v1/scheduled_statuses) - Schedule posts
  • Markers (/api/v1/markers) - Timeline position markers
  • Push Notifications (/api/v1/push/subscription) - Web Push

Admin Endpoints

Admin endpoints (/api/v1/admin/*) for instance administration are not yet implemented.

Account Management

  • PATCH /api/v1/accounts/update_credentials - Update account profile
  • POST /api/v1/accounts - Account registration
  • DELETE /api/v1/profile/avatar - Delete avatar
  • DELETE /api/v1/profile/header - Delete header image

Known Issues

Some endpoints have known issues being worked on:

EndpointIssue
GET /api/v1/accounts/lookupJSON encoding error
GET /api/v1/accounts/searchJSON encoding error
POST /api/v1/accounts/{id}/followDatabase transaction error
POST /api/v1/appsOAuth client creation issue

Making Requests

Authentication

Most endpoints require authentication. Include your access token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your-instance.example.org/api/v1/timelines/home"

See the Authentication Guide for how to obtain tokens.

Pagination

List endpoints support cursor-based pagination using Link headers:

curl -i "https://your-instance.example.org/api/v1/timelines/home?limit=20"

The response includes a Link header with next and prev URLs:

Link: <https://...?max_id=123>; rel="next", <https://...?min_id=456>; rel="prev"

Common pagination parameters:

ParameterDescription
limitMaximum number of results (default: 20, max: 40)
max_idReturn results older than this ID
min_idReturn results newer than this ID
since_idReturn results newer than this ID (inclusive)

Rate Limiting

The API implements rate limiting. When you exceed the limit, you'll receive a 429 Too Many Requests response. Check the following headers:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed
X-RateLimit-RemainingRequests remaining in window
X-RateLimit-ResetWhen the limit resets (UTC)

See Also