Developer API

Software can read and write to this server over HTTP. There are three interfaces and which one you want depends on what you are building.

The Mastodon-compatible API

Endpoints under /api/v1 and /api/v2 implement the Mastodon client API. A Mastodon client that asks you to type in a server name works against this one unchanged: timelines, statuses, notifications, accounts, relationships, search, media upload, filters, lists and bookmarks are all there.

Two endpoints describe the server itself and need no credentials: /api/v1/instance and /api/v2/instance carry its name, its description, its posting limits and whether registration is open.

The extended API

Endpoints under /api/v1.1, /api/pixelfed/v1 and /api/pixelfed/v2 carry what the photo-sharing apps need and Mastodon does not define: the composer, the discover surface, stories, direct messages and the account settings screens. The paths keep their historical names so existing clients keep working against them unchanged.

Authorising a client

Both APIs use OAuth 2. The flow is the standard one:

1. Register your application at /settings/applications, or programmatically with POST /api/v1/apps.
2. Send the person you are acting for to /oauth/authorize with your client id, redirect URI and the scopes you need.
3. Exchange the code they come back with for a token at /oauth/token.
4. Send the token as an Authorization: Bearer header on every request.

Ask for the narrowest scopes that do the job — a token is only as safe as the smallest thing it can do. If you are writing a script for your own account rather than an app for other people, mint a personal access token at /settings/developers instead and skip the authorisation flow entirely.

Federation and feeds

Not everything needs a token. These are public documents:

• GET /.well-known/webfinger?resource=acct:[email protected] resolves a handle to an account.
• GET /.well-known/nodeinfo points at /api/nodeinfo/2.0.json, which reports the software this server runs, its version and its user counts.
• GET /users/{username}.atom is an account's public posts as an Atom feed.
• An account's ActivityPub actor, inbox and outbox are served from its profile URL when the request asks for application/activity+json.

Rate limits

Requests are limited per token and per address. A limited request answers 429 and says when to try again; treat that as the signal to back off rather than as an error to retry immediately.

Before you ship

The rules that apply to software talking to this server are on the Platform and API terms page. They are short, and the one that catches people out is that a post which is not public is not public data just because a token can read it.

This server is at https://nicagram.com.