/v1 and served from https://api.tuor.dev. This page covers what applies to every endpoint; each endpoint has its own page under Endpoints, generated from the API’s OpenAPI spec, with request and response schemas and a playground for trying it with your key.
Authentication
Send your API key in theX-API-Key header:
Limits and payload constraints
The ingest limit is 60 trace creates per minute per organization, shared by all of its API keys. Every integration endpoint has its own per-route limit and returns429 Too Many Requests with Retry-After when exceeded.
Every JSON payload field is independently validated:
- Maximum size: 5 MB per field.
- Maximum nesting depth: 10 levels.
422 Unprocessable Entity.
The total request body is capped at 20 MiB; larger requests are rejected with 413 Payload Too Large.
Core endpoints
Most integrations do not need the rest on day one: trace lifecycle automation (review, reset, delete, restore), and project and tag administration are usually handled in the Web Console. Lifecycle writes require
expected_version to prevent conflicting writes. Webhook receiver setup is covered in Webhooks.
Review results
A trace starts aspending and later becomes approved, rejected, or corrected. final_output is the authoritative result: the original model_output if approved, corrected_output if corrected, and null if rejected or still pending. trace_config is round-tripped unchanged.
The detail response also includes events, the trace’s review history in ascending trace-version order. Exports and list items leave events out; fetch the trace when you need them.
Tags
Tags are optional. Use them when you need to route review work or export a specific cohort. Create and manage tags in the Web Console under Settings → Tags. Integration code needs tag IDs, not tag names: callGET /v1/tags/ and store the id of each tag you plan to apply. A trace can have up to 10 tags.
Exports
GET /v1/traces/export streams one JSON object per line. Filter with status (commonly approved or corrected for training and eval datasets), project_id, tag, and from_date/to_date on created_at. exclude_fields takes comma-separated dot paths and removes nested keys through arrays, which keeps base64 media out of the stream:
Span format
Thespans array on POST /v1/traces/ is a flat ordered list. Create spans omit id; Tuor assigns one to every returned span. The span types are message, reasoning, tool_request, tool_response, and error:
message, reasoning, and tool_request spans accept an optional model naming the model that produced them, so a trace that uses several models says which wrote what.
tool_request made through an MCP server may name it in an optional server, as in "server": "github". Set "invalid_json": true when the call’s arguments were meant to be JSON but don’t parse, and keep them as written in content.
is_error to true when the tool call failed, and keep the failure’s details in content.
error span records a failure that isn’t a tool result, such as a provider error. Keep provider-specific details in content.
Every span’s content is an ordered list of text, json, encrypted, refusal, image, or document blocks. Base64 media uses:
filename is optional. An image the trace links to rather than embeds uses a url source: {"type": "image", "source": {"type": "url", "url": "https://example.com/chart.png"}}.
Spans or blocks Tuor doesn’t recognize are kept unchanged in an unknown span, so nothing you send is lost. If your traces don’t fit this format, get in touch.
Error responses
Errors are returned as JSON:
For anything this reference doesn’t cover, email support@tuor.dev.