API Reference

Main GraphQL HTTP

Encrypted requests for a signed-in session.

key = Base64Decode(session.token)Authenticated session; c-id = clientId

Client
https://<host>:<port>/graphql
Server

POST /graphql

c-id: 706c6169-3b80-8f42-9a61-4e312e54d001

HTTP · binary

JSON({ requestId, query, variables })

requestId is UUIDv7 and contains the request time. variables, operationName and extensions are optional.

Use a fresh UUIDv7 requestId for every request. Its time must be within ±30 minutes of the server. UUID values are deduplicated in memory.

XChaCha20-Poly1305 · Hover or tap a field
1 / 2

Replay protection

requestId = UUIDv7()JSON { requestId, query, variables } → authenticated encryption
↓ POST /graphql
Authenticate and decryptsession.token✕ → Reject
↓
Check UUIDv7 time|serverTime − requestId timestamp| ≤ 30 min✕ → Reject
↓
Record requestId before executionsession → request-ID set
✓ ↓Execute GraphQL
✕ ↓Reject reused requestId
Bearer API Token: JSON over HTTPS, without body encryption →
Library calls

Desktop excerpts. graphqlRequestPayload creates UUIDv7 requestId. Encrypt JSON with AAD binding HTTP_REQUEST, POST and the logical endpoint, then validate response binding.

typescript
// plain-desktop/src/lib/api/gql-client.ts
const payload = graphqlRequestPayload(query, variables)
const requestBody = chachaEncrypt(key, payload, httpRequestAad('/graphql'))
const response = await httpRequest(url, {
  method: 'POST', headers: { 'c-id': clientId }, body: requestBody
})
if (!response.ok) throw new Error(String(response.status))
const bytes = new Uint8Array(await response.arrayBuffer())
const result = JSON.parse(decryptGraphqlResponse(key, requestBody, bytes))
// Feature error codes are carried in extensions.code; message is diagnostic text.
if (result.errors?.length) throw GqlError.fromGraphql(result.errors[0])

HTTP 401: missing or invalid session. A saved session key survives restart; revocation or replacement invalidates it. HTTP 400: malformed, stale or repeated requestId. HTTP 429: replay cache full.