Zennvue API

Scoped REST API for reading organization data and safely automating task workflows.

v1Base URL: https://platform-zennvue.com/api/v1

Plan requirement

API access is available on the Studio plan and above. If your plan doesn’t include API access, requests will return 403 tier_required.

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer znv_live_a1b2c3d4...

Issue keys from your dashboard at Settings → API Keys. Keys are shown once at creation. Store them somewhere safe and grant only the scopes an integration needs. Existing read-only keys retain data:read; task automation requirestasks:write.

Quick example

curl https://platform-zennvue.com/api/v1/clients \
  -H "Authorization: Bearer znv_live_..." \
  -H "Accept: application/json"

Returns JSON in the shape { data: Client[], pagination: { page, pageSize, total, totalPages } }.

Idempotent writes

Every POST or PATCH request requires an Idempotency-Key header containing 8–128 safe characters. Repeating the same operation and body with the same key replays the original response. Reusing a key with different data returns 409 idempotency_conflict.

curl -X POST https://platform-zennvue.com/api/v1/tasks \
  -H "Authorization: Bearer znv_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: make-run-20260818-001" \
  -d '{"title":"Confirm vendor arrival","priority":"HIGH"}'

Outbound webhooks

Configure signed client, proposal, contract, invoice, payment, event, and task lifecycle deliveries under Settings → API Keys. Zennvue signs timestamp.body with HMAC-SHA256 and sends the result in X-Zennvue-Signature. Deliveries use a stable idempotency key, retry with backoff, and surface endpoint health and dead letters in settings.

Endpoints

Method	Path	Description
GET	/clients	List clients, paginated. Filter by status, tag, or search.
GET	/events	List events, paginated. Filter by status, date range, client.
GET	/proposals	List proposals, paginated. Filter by status or client.
GET	/contracts	List contracts, paginated. Filter by status or client.
GET	/invoices	List invoices, paginated. Filter by status or client.
GET	/payments	List payments, paginated. Filter by invoice, client, status, method, or date.
GET	/tasks	List tasks, paginated. Filter by status.
POST	/tasks	Create a task with the tasks:write scope and an idempotency key.
PATCH	/tasks/{taskId}	Update a task with optimistic concurrency and idempotent replay.

Pagination

All list endpoints accept ?page=1 (1-indexed) and ?pageSize=50 (clamped to [1, 200]). The response envelope always includes a pagination object with { page, pageSize, total, totalPages }.

Rate limits

Each API key is limited to 1,000 reads per hour and 200 writes per hour. The applicable limit and remaining requests are returned on every response in the X-RateLimit-Limit and X-RateLimit-Remaining headers. Exceeding the limit returns 429 with a Retry-After header telling you how long to wait.

Errors

Errors come back as JSON with a stable error.code:

401 missing_api_key: no Authorization header
401 invalid_api_key: the key wasn’t recognized
401 key_revoked: the key was revoked
401 key_expired: the key passed its expiration date
403 tier_required: your plan doesn’t include API access
403 insufficient_scope: the key lacks the required endpoint scope
400 invalid_idempotency_key: the write is missing a valid retry key
409 idempotency_conflict: the retry key was reused with different data
409 task_changed: the task changed after the caller read it
422 invalid_assignee, invalid_event, or invalid_client: a referenced record is outside the organization or missing
429 rate_limited: over the per-key rate limit

OpenAPI spec

Drop this into Postman, Insomnia, or Stainless for an auto-generated client:

/api/v1/openapi.json