Skip to content
z4j docs

API overview

z4j exposes two APIs:

  • REST at /api/v1/* for the dashboard, external automation, and tooling.
  • WebSocket at /ws/agent for agents. The dashboard uses the separate /ws/dashboard endpoint. Documented in websocket-protocol.

Authentication

Section titled “Authentication”
  • Dashboard / user: session cookies issued by POST /api/v1/auth/login.
  • External tools: API keys minted at Dashboard, Settings, API keys. Tokens begin with z4k_ and are sent as Authorization: Bearer z4k_....
  • Agents: bearer token minted via POST /api/v1/projects/{slug}/agents. Returned with a paired per-project HMAC secret used to sign every frame.

See authentication.

Versioning

Section titled “Versioning”
  • Version prefix in the URL: /api/v1/.
  • Breaking changes require a new major (/api/v2/); additive changes (new optional fields, new endpoints, new query params with safe defaults) happen within v1.
  • API keys carry scopes; new scopes can be added without bumping the version.

Content types

Section titled “Content types”
  • Requests: JSON.
  • Responses: JSON for normal endpoints; CSV / XLSX when an endpoint accepts ?format= (audit, tasks).
  • Errors: JSON envelope (see errors).

Pagination

Section titled “Pagination”

List endpoints that paginate use opaque cursors:

{
  "items": [],
  "next_cursor": "..."
}

Pass the cursor back as ?cursor=... for the next page. When next_cursor is absent or null, the result is the last page. Some smaller collections instead return a bare JSON array; consult the individual endpoint page rather than assuming one response envelope for every list route.

Rate limiting

Section titled “Rate limiting”

Endpoint-level limits cover authentication and invitations as well as selected operational routes, including bulk task actions, agent connects, channel tests and imports, OpenAPI, setup, and MFA. Some routes share a bucket. Failing requests return 429 Too Many Requests. The brain does not currently emit X-RateLimit-* headers; rely on the 429 and back off. See authentication for the authentication buckets.

Endpoint catalog

Section titled “Endpoint catalog”

Project-scoped (under /api/v1/projects/{slug}/):

REST root-level (under /api/v1):

  • authentication under /auth/
  • projects at /projects
  • API keys at /api-keys
  • Public invitations at /invitations/preview and /invitations/accept

Outside the REST version prefix:

  • metrics at the bare /metrics path