> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Authenticate, choose a base URL, and call the Zespan Public API directly or through the SDKs.

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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.zespan.com/v1/prompts \
  -H "x-api-key: $ZESPAN_API_KEY"
```

<Warning>
  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.
</Warning>

Create and rotate keys from your project settings in the Zespan dashboard. See
[API keys](/account/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

<CardGroup cols={2}>
  <Card title="Ingest traces" icon="upload">
    Send trace and span events with the native NDJSON endpoint, or via OpenTelemetry.
  </Card>

  <Card title="Prompts" icon="file-text">
    Fetch and manage versioned prompts, labels, tags, and folders.
  </Card>

  <Card title="Datasets" icon="database">
    Read datasets and drive dataset runs and scoring.
  </Card>

  <Card title="Guardrails" icon="shield">
    Evaluate text against your project's guardrails at runtime.
  </Card>
</CardGroup>

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