Skip to main content
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

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.
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 (/v1/ingest, /v1/traces) share the same limits: 300 requests per minute per API key. When you exceed the limit the API responds with 429 and a Retry-After header telling you how many seconds to wait. Both ingestion endpoints also cap request size at 1 MB, and both 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.

​
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.