API reference

The Zespan Public API is the surface your application and the Zespan SDKs call at runtime: send traces, manage prompts, drive dataset experiments, and check guardrails. Every endpoint is versioned under /v1 and returns JSON.

Base URL

https://api.zespan.com

All paths in this reference are shown with the /v1 prefix, for example POST https://api.zespan.com/v1/ingest.

Authentication

Every endpoint in this reference authenticates with a project API key sent in the x-api-key header. A key scopes the request to exactly one project, so project-scoped endpoints infer the project from the key and the projectId parameter is optional.

curl https://api.zespan.com/v1/prompts \
  -H "x-api-key: $ZESPAN_API_KEY"

Treat your API key like a password. Set it from an environment variable or secret store, never commit it to source control, and rotate it from the dashboard if it is exposed.

Create and rotate keys from your project settings in the Zespan dashboard. See API keys for details.

Guardrail policy changes are not API-key accessible

Reading and applying guardrail policy-as-code checks the acting user’s role in the organization, which a project key cannot supply — a key identifies a project, not a person. Those actions are therefore outside this API and refuse a project API key rather than partially honouring it. Perform them from the dashboard, or with zespan policy after zespan auth login.

Ingest and the rest of this reference are unaffected. /v1/ingest, /v1/traces, /v1/guardrails/check and every other endpoint documented here continue to authenticate with x-api-key, exactly as before.

Rate limits

Ingestion endpoints have separate limits per project. /v1/ingest allows 300 requests per minute, and /v1/traces (OTLP) allows 3,000 requests per minute by default. POST /v1/sdk/client-reports (the counts-only lost-event reports the SDKs send) allows 600 requests per minute per project. When you exceed a limit the API responds with 429 and a Retry-After header telling you how many seconds to wait. If Zespan can’t check the limit for a moment, it answers 503 with a Retry-After header rather than accepting unmetered traffic. Repeated requests with an invalid API key are also throttled with 429. When the ingest queue is far behind, /v1/ingest and /v1/traces can answer 503 with code ingest_overloaded and a Retry-After header instead of accepting more. Nothing is queued and no quota is used, so retry after the wait. Events count against your monthly quota only after the batch has been queued. A 503 with code QUEUE_UNAVAILABLE uses no quota, so retrying it costs nothing. After you rotate a project API key, the new key works immediately and the old key keeps working for 24 hours on both /v1/ingest and /v1/traces. When the ingest queue is behind (or the queue’s Redis is short of memory), /v1/ingest and /v1/traces may answer 503 with the code ingest_overloaded and a Retry-After header (about 5 to 15 seconds) instead of accepting more events. Nothing from that request is stored; retry after the wait. The Zespan SDKs do this automatically. Request size is capped after decompression: /v1/ingest at 4 MiB (the SDKs send about 3.5 MB per request before gzip) and /v1/traces at 8 MiB. Both ingestion endpoints count against your organization’s monthly event quota — but their per-request event caps differ: /v1/ingest caps at 100 events per request, while /v1/traces (OTLP) caps at 512 spans per request, matching the OpenTelemetry SDK/Collector’s own default max_export_batch_size. A batch over 512 spans sent to /v1/traces returns 202 with the overflow reported in partialSuccess.rejectedSpans — lower your exporter’s max batch size rather than relying on the cap. The OTLP metrics (/v1/metrics) and logs (/v1/logs) endpoints are not implemented and return 501. Send traces to /v1/traces.

Idempotent ingest

Send an optional Idempotency-Key header on POST /v1/ingest so that a retried request is never ingested twice. The key is 1 to 128 characters from A-Z a-z 0-9 . _ : -. The SDKs set it for you and reuse it on every retry of the same batch.

Situation	Response
First request with a key	`202 { "accepted": n, "cv": ... }`
Repeat of an accepted request (same key, same body)	`202 { "accepted": n, "cv": ..., "replayed": true }` with the header `Idempotent-Replayed: true`. Nothing is queued or counted again.
Malformed key	`400` `INVALID_IDEMPOTENCY_KEY`
Same key still being processed	`409` `IDEMPOTENCY_IN_PROGRESS` with `Retry-After: 2`. Retry with the same key.
Same key, different body	`422` `IDEMPOTENCY_KEY_REUSED`

A key is remembered for 6 hours after its batch is accepted.

Errors

Every error body includes a requestId, an error message, and a message with the same text. Most errors also include a stable code, and validation errors list the failing fields in details:

{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34"
}

Every response carries an x-request-id header with the same value. If your proxy already sets x-request-id to 8 to 64 letters, digits, ., _ or -, Zespan keeps it; any other value is replaced. Quote the request id when you contact support. Responses with status 429 or 503 include a Retry-After header in whole seconds (at least 1). Wait that long before retrying.

Code	Status	Meaning
`rate_limit_exceeded`	429	Too many requests. Honour `Retry-After`.
`service_unavailable`	503	A dependency is briefly unavailable. Retry after `Retry-After`.
`QUEUE_UNAVAILABLE`	503	Ingest could not queue the batch. Nothing was counted against your quota. Retry the same batch.
`quota_exceeded`	429	Monthly trace quota reached on a plan that soft-limits. `Retry-After` is 60.
`quota_hard_exceeded`	429	Monthly trace quota reached on a plan with a hard limit.
`INVALID_IDEMPOTENCY_KEY`	400	The `Idempotency-Key` header is malformed.
`IDEMPOTENCY_IN_PROGRESS`	409	A request with this key is still being processed.
`IDEMPOTENCY_KEY_REUSED`	422	The key was already used with a different body.
`INVALID_CURSOR`	400	A dataset `cursor` is malformed.
`AI_PROCESSING_DISABLED`	403	Your organization has turned off AI processing. See Organizations → AI processing.
`ORG_SUSPENDED`	403	The organization is suspended.
`NOT_FOUND`	404	The resource or route doesn’t exist.
`VALIDATION_ERROR`	400	The request failed validation; `details` lists the fields.

What you can do

Ingest traces

Send trace and span events with the native NDJSON endpoint, or via OpenTelemetry.

Prompts

Fetch and manage versioned prompts, labels, tags, and folders.

Datasets

Read datasets and drive dataset runs and scoring.

Guardrails

Evaluate text against your project’s guardrails at runtime.

See the endpoint list in the sidebar for full request/response schemas.

Overview

Ingestion

Prompts

Datasets

Guardrails

SDK / CLI support

Blast Radius

Outcomes

Compliance

Models

Model Lifecycle

Policies

Demo

Base URL

Authentication

Guardrail policy changes are not API-key accessible

Rate limits

Idempotent ingest

Errors

What you can do

Ingest traces

Prompts

Datasets

Guardrails

​Base URL

​Authentication

​Guardrail policy changes are not API-key accessible

​Rate limits

​Idempotent ingest

​Errors

​What you can do

Ingest traces

Prompts

Datasets

Guardrails

Base URL

Authentication

Guardrail policy changes are not API-key accessible

Rate limits

Idempotent ingest

Errors

What you can do