Developers

The API is switched off on this server. Everything below describes what it does when it is on. The endpoints answer 404 until the operator switches it back on, and applications you register cannot be authorized in the meantime.

There is no public API on this server yet. Rather than a page promising one, here is exactly what exists today and what it will look like.

Getting A Token

OAuth 2.0, authorization code with PKCE, and nothing else. There is no implicit flow, because it puts a token in an address bar and therefore in history and in referrer headers, and no password grant, because it asks an application to handle somebody's password, which is the thing OAuth exists to avoid.

1. Register an application at Settings, then Applications. You get a client id and a secret, once.
2. Send somebody to /oauth/authorize with your client id, redirect address, response_type=code, the scopes, and an S256 code_challenge.
3. They arrive back at your address with a code, worth one exchange and five minutes.
4. POST /oauth/token with the code, the same redirect address and your code_verifier.

This server will only ever send somebody back to an address the application registered, so a stolen code cannot be redeemed anywhere else.

The token comes back with an expires_in, and it is ninety days. There is no refresh token: when it runs out, send the person through /oauth/authorize again, where they see what they are agreeing to a second time. A token that never expires is a password somebody wrote down, and one that leaks stays useful until a person happens to notice. An expired token answers 401 with invalid_token, so you can tell it from a revoked one.

Scopes

• read — ribbits, profiles and timelines the account can already see
• write — post, reply, react and re-ribbit as the account
• follow — follow and unfollow as the account
• messages — read and send the account's direct messages

Four, on purpose. A list of thirty is a list nobody reads before pressing Allow.

The Endpoints

Send the token as Authorization: Bearer. Everything answers JSON.

• GET /api/v1/me — the account, and which scopes this token carries
• GET /api/v1/timeline — the home timeline, newest first
• GET /api/v1/accounts/{handle} and /ribbits
• GET /api/v1/ribbits/{id}
• GET /api/v1/search?q= — the same query language as the site
• GET /api/v1/notifications
• GET /api/v1/standing — every limit on the account, in full
• POST /api/v1/ribbits — a JSON object with text
• POST /api/v1/ribbits/{id}/react?kind= and /repost
• POST /api/v1/accounts/{handle}/follow

Lists page with ?before= and an id, because the ordering is ids. There is nothing else to page by on a site with no ranking.

Rate Limits

300 reads and 100 writes per token per fifteen minutes. Every response carries X-Rate-Limit-Limit, -Remaining and -Reset, including the ones that worked, so an application can slow down before it is refused rather than after.

The same numbers are on the account's standing page. A limit nobody can see is not a limit, it is a secret.

Two Promises

An application sees exactly what the account it acts for would see on the site. There is no ranking for programs, and no data an application can read that the person it belongs to cannot.

An application can never do more than the account can. If an account is limited, everything acting as it is limited the same way, for the same written reason, which /api/v1/standing returns in full.