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

# Integration API

> Send traces, fetch review results, tag cohorts, and export reviewed data.

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:

```http theme={null}
X-API-Key: tuor_AbCdEf123...
```

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

| Method | Path | Use when |
| - | - | - |
| `POST` | [`/v1/traces/`](https://docs.tuor.dev/api-reference/traces/create-trace) | Send an ordered model trajectory and structured output to Tuor for review. |
| `GET` | [`/v1/traces/{trace_id}`](https://docs.tuor.dev/api-reference/traces/get-trace) | Fetch one trace and its current review result. |
| `GET` | [`/v1/traces/`](https://docs.tuor.dev/api-reference/traces/list-traces) | List or filter traces by project, status, or tag. |
| `GET` | [`/v1/traces/export`](https://docs.tuor.dev/api-reference/traces/export-traces) | Stream reviewed traces as JSONL for evals, dashboards, or training pipelines. |
| `GET` | [`/v1/tags/`](https://docs.tuor.dev/api-reference/tags/list-tags) | List tags and copy IDs for trace tagging or export filters. |
| `POST` | [`/v1/traces/{trace_id}/tags`](https://docs.tuor.dev/api-reference/traces/add-tags-to-trace) | Attach tags for routing, cohorting, or downstream filtering. |
| `DELETE` | [`/v1/traces/{trace_id}/tags/{tag_id}`](https://docs.tuor.dev/api-reference/traces/remove-tag-from-trace) | Remove a tag from a trace. |

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](https://docs.tuor.dev/reference/webhooks.md).

## 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/`](https://docs.tuor.dev/api-reference/tags/list-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`](https://docs.tuor.dev/api-reference/traces/export-traces) 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:

```bash theme={null}
curl "https://api.tuor.dev/v1/traces/export?status=corrected&exclude_fields=spans.content.source.value" \
  -H "X-API-Key: $TUOR_API_KEY"
```

## Span format

The `spans` array on [`POST /v1/traces/`](https://docs.tuor.dev/api-reference/traces/create-trace) 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`:

```json theme={null}
{"type": "reasoning", "role": "assistant", "model": "claude-opus-4-6", "content": [{"type": "text", "value": "I should verify the total."}]}
```

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

```json theme={null}
{
  "type": "tool_request",
  "role": "assistant",
  "call_id": "lookup_1",
  "name": "lookup_invoice",
  "content": [{"type": "json", "value": {"invoice_id": "inv_123"}}]
}
```

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

```json theme={null}
{
  "type": "tool_response",
  "role": "tool",
  "call_id": "lookup_1",
  "is_error": false,
  "content": [{"type": "json", "value": {"total": 1250.45}}]
}
```

Set `is_error` to `true` when the tool call failed, and keep the failure's details in `content`.

```json theme={null}
{
  "type": "error",
  "role": "system",
  "content": [{"type": "json", "value": {"type": "overloaded_error", "message": "Overloaded"}}]
}
```

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:

```json theme={null}
{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/png",
    "filename": "chart.png",
    "value": "iVBORw0KGgo..."
  }
}
```

`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](mailto:support@tuor.dev).

## Error responses

Errors are returned as JSON:

```json theme={null}
{ "detail": "Invalid or revoked API key" }
```

Common status codes:

| Status | Meaning |
| - | - |
| `400` | Malformed request. |
| `401` | Missing or invalid API key. |
| `402` | Trace limit reached. |
| `403` | This API key isn't allowed to perform this action. |
| `404` | Resource does not exist or is not visible to this organization. |
| `409` | Optimistic-lock mismatch or forbidden lifecycle transition. |
| `422` | Payload exceeds size/depth limits or fails schema validation. |
| `429` | Rate limit exceeded. Respect `Retry-After`. |

For anything this reference doesn't cover, email [support@tuor.dev](mailto:support@tuor.dev).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.