API

Unixgram API

The app talks to the server over an ordinary HTTP API. It is the same for the web and for native clients, and it is shaped so a response can be parsed without knowing in advance what went wrong.

One envelope for every response

Success and failure differ by the success field, not by the set of keys. A client never has to guess the shape of a response from the status code — it always parses the same way.

// success
{ "success": true, "data": { "post": { "id": "..." } } }

// failure
{ "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [] } }

Protecting mutating requests

Every request that changes data must carry an x-csrf-token header matching a previously issued cookie. It is a double-submit scheme with an HMAC signature: the header cannot be forged without the cookie, and the browser will not let another origin read the cookie.

GET  /api/auth/csrf        → issues the cookie + token
POST /api/social/posts
     x-csrf-token: <token from the cookie>
     content-type: application/json

Rate limiting

Sensitive routes — sign-in, registration, password recovery, code delivery — are rate limited per source. Exceeding the limit returns 429 with a header saying when to retry.

Realtime events

The event stream is delivered over UnixProto, falling back to plain Server-Sent Events on /api/realtime/events. Event names form a closed set: a new event must be added on the server and the client together, or it is silently dropped.

message:new     a new message in a chat
post:deleted    a post was deleted
feed:new        new posts in the feed
stars:balance   the star balance changed

Public access keys and per-method documentation are in preparation. For now the API is aimed at Unixgram's own clients.