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

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