API overview

z4j exposes two APIs:

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

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

• 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

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

Pagination

List endpoints use opaque cursor pagination:

{
  "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.

Rate limiting

Endpoint-level limits are enforced on auth, password reset, and invitation flows; see authentication for the live numbers. Failing requests return 429 Too Many Requests. The brain does not currently emit X-RateLimit-* headers; rely on the 429 and back off.

Endpoint catalog

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

• tasks, commands (issued via the tasks page)
• schedules
• agents
• memberships and invitations
• audit

Root-level:

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