API basics

Base URL

Every public route lives under /api/v1 on your ZeroReach host. Locally the API runs on http://localhost:8000. The examples use an environment variable:

export ZEROREACH_URL="http://localhost:8000"

One host serves everything: the core answers the public routes itself and forwards the AI routes (knowledge base, research, replies, AI drafts and other AI features) to the AI service behind it, with the same authentication and scope checks.

The OpenAPI document

The server describes itself at GET /api/v1/openapi.json (no authentication). It is the same merged document this site's API reference is generated from.

Requests and responses

• Request and response bodies are JSON (Content-Type: application/json), except file uploads and exports.
• IDs are UUIDs (most are UUIDv7, so they sort by creation time).
• Timestamps are ISO 8601 date-times in UTC.
• Errors use one shape: {"detail": ...}. See Errors and limits.

Pagination

List endpoints use keyset (cursor) pagination:

• Results are newest first.
• limit sets the page size (each route documents its range).
• The answer is {"items": [...], "next_cursor": "..."}. Pass next_cursor as cursor to get the next page; it is null on the last page.

Cursors are opaque strings: don't build or change them.

curl -s "$ZEROREACH_URL/api/v1/leads?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $ZEROREACH_API_KEY"

Multi-tenancy

Every record belongs to a workspace, and every query filters on it. With an API key, the workspace is the key's. With a session token, send X-Workspace-Id. An id from another workspace answers exactly like a missing one (404).