Most operations require authentication. Send a token in the Authorization header as a Bearer token on every request:

Authorization: Bearer <token>

Two kinds of token are accepted, distinguished by prefix:

• JWT — obtained from the login mutation; used by the web app.
• Personal API key (prefix oak_) — for programmatic access, created with createApiKey when the apiKeysEnabled policy is on. The secret is shown only once, at creation.

Unauthenticated requests are allowed for public operations (e.g. Post, searchPosts, Category); everything else resolves the current user from the token.

Beyond being logged in, many operations require a specific permission. Each operation's description states what it needs — e.g. "Requires the content.moderate permission" or "Restricted to the author".

Permissions are granted through roles (dynamic, admin-managed). A caller's effective permissions can be read with myPermissions. Some rights are additionally gated by a runtime feature policy (e.g. apiKey.create only applies while apiKeysEnabled is on). Moderator- and owner-grade actions also respect an "act-on" hierarchy that prevents acting on higher-ranked users.

Responses follow the GraphQL convention: data carries the result and an errors array carries any problems, each with a message and a path. Authorization failures surface as a top-level error with the message Not Authorized!. A partial data payload alongside errors is normal when only some fields fail.

Live updates (new notifications, chat messages, room and policy changes) are delivered via GraphQL subscriptions over WebSocket using the graphql-ws protocol, on the same endpoint. Pass the same Authorization header in the connection parameters.

subscription {
  notificationAdded {
    id
    reason
    read
  }
}

File and image uploads use the GraphQL multipart request spec via the Upload scalar. Avatars and post images take an ImageInput (upload field), chat attachments take a FileInput. Non-multipart clients may instead reference already-hosted assets by URL.

The schema carries ActivityPub identifiers (actorId, activityId, objectId, publicKey) on users, posts and comments for federation with other instances. Most clients can ignore these fields.

A few representative operations. Send variables alongside each query and the Authorization header (except for login).

Log in and obtain a JWT

mutation (: String!, : String!) {
  login(email: , password: )
}

The current user

query {
  currentUser {
    id
    slug
    name
    avatar { url }
  }
}

Create a post

mutation (: String!, : String!, : [ID]) {
  CreatePost(title: , content: , categoryIds: ) {
    id
    slug
  }
}

A page of the feed

query (: Int, : Int, : [_PostOrdering]) {
  Post(first: , offset: , orderBy: ) {
    id
    title
    createdAt
    author { id name }
    commentsCount
    shoutedCount
  }
}

Send a chat message

mutation (: ID, : String) {
  CreateMessage(roomId: , content: ) {
    id
    content
    createdAt
  }
}