Skip to main content
Use the Tuor API from your backend service to send model traces and retrieve reviewed outputs. The Web Console handles organization setup, project creation, API key management, analytics, and reviewer workflows. All integration endpoints are versioned under /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 the X-API-Key header:
API keys are created in the Web Console and are scoped to the organization that issued them. Store them server-side only; do not expose them in browser code.

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 returns 429 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.
Oversize or over-nested payloads are rejected with 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 as pending 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: call GET /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

The spans 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.
A 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.
Set is_error to true when the tool call failed, and keep the failure’s details in content.
An 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:
Common status codes: For anything this reference doesn’t cover, email support@tuor.dev.