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 emits no 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}/):

  • tasks at /tasks, with the /commands routes (retry, cancel, bulk retry, purge, worker control) on the same page; that page also points at /bulk-retry-requests and /agent-workers
  • dead letters at /dead-letters: a read-only listing served through an online agent that advertises list_dead_letters for the engine; see tasks for the requeue command
  • schedules at /schedules
  • agents at /agents
  • memberships and invitations at /memberships and /invitations
  • audit at /audit, with background exports at /audit/export-jobs (see audit exports)
  • automation at /automation/rules and /automation/settings
  • notifications at /notifications
  • dashboard data at /stats, /trends, /queues, /workers, /issues, /events and /saved-views

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

  • authentication under /auth/, including the MFA routes under /auth/mfa/
  • projects at /projects
  • API keys at /api-keys (see authentication)
  • Public invitations at /invitations/preview and /invitations/accept
  • users and admin at /users, /admin/settings, /admin/system, /admin/audit-forwarder and /setup
  • user notification channels, subscriptions and inbox under /user/
  • activity feed at /activity
  • scheduler fleet: GET /api/v1/schedulers fans out to the configured scheduler /info URLs and returns one entry per scheduler; global brain admin only
  • dashboard data at /home and the health probes /health, /health/ready, /health/system and /health/deep
  • agent long-poll transport at POST /agent/events and GET /agent/commands
  • OpenAPI schema and Swagger UI at /openapi.json and /docs (visibility is operator-configurable: public, private or disabled)

Outside the REST version prefix:

  • metrics at the bare /metrics path
  • the first-boot setup form at GET /setup (HTML)