Skip to content
z4j docs

API overview

The z4j brain exposes two APIs:

  • REST at /api/v1/* - for the dashboard, external automation, and integration with other tools.
  • WebSocket at /ws - for agents. Documented in websocket-protocol.

Authentication

Section titled “Authentication”
  • Dashboard / user - session cookies from /api/v1/auth/login.
  • External tools - personal access tokens (PATs) via the dashboard at Settings → Tokens.
  • Agents - bearer tokens minted via Agents → Mint token.

See authentication.

Versioning

Section titled “Versioning”
  • Version prefix in URL: /api/v1/.
  • Breaking changes require a new major (/api/v2/). We will maintain v1 for at least 12 months after v2 ships.
  • Additive changes (new fields, new endpoints) happen within v1.

Content types

Section titled “Content types”
  • Requests: JSON.
  • Responses: JSON.
  • Errors: RFC 7807 Problem Details format (see errors).

Pagination

Section titled “Pagination”

List endpoints use cursor pagination:

{
  "items": [...],
  "next_cursor": "eyJpZCI6...",
  "has_more": true
}

Pass the cursor back in ?cursor=... for the next page.

Rate limits

Section titled “Rate limits”

Per-endpoint limits documented on each section. Headers on every response:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset (Unix ts)

See rate limits.

Full endpoint list

Section titled “Full endpoint list”

See the sidebar: