Integration API¶

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. Examples use https://api.tuor.dev as the base URL.

Authentication¶

Send your API key in the X-API-Key header:

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 default ingest limit is 200 trace creates per minute. Other integration endpoints have lower per-route limits and return 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.

Core endpoints¶

Method	Path	Use when
`POST`	`/v1/traces/`	Send a model input/output pair to Tuor for review.
`GET`	`/v1/traces/{trace_id}`	Fetch one trace and its current review result.
`GET`	`/v1/traces/`	List or filter traces by project, status, or tag.
`GET`	`/v1/traces/export`	Stream reviewed traces as JSONL for evals, dashboards, or training pipelines.
`GET`	`/v1/tags/`	List tags and copy IDs for trace tagging or export filters.
`POST`	`/v1/traces/{trace_id}/tags`	Attach tags for routing, cohorting, or downstream filtering.
`DELETE`	`/v1/traces/{trace_id}/tags/{tag_id}`	Remove a tag from a trace.

Webhook receiver setup is covered separately in Webhooks.

Send a trace¶

`POST /v1/traces/`¶

Creates a new trace with status pending.

Request body

Field	Type	Required	Notes
`project_id`	string	yes	The project that owns this trace. Copy it from the project's ID column in the Web Console.
`model_input`	object	yes	What your model saw. Shape it for the project input type.
`model_output`	object	yes	What your model produced. Shape it for the project output type.
`trace_config`	object	no	Metadata such as `model`, `temperature`, `internal_run_id`, or `prompt_version_id`. Echoed in webhooks and exports.

curl -X POST "https://api.tuor.dev/v1/traces/" \
  -H "X-API-Key: $TUOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "model_input": {
      "content": "Extract company name from this invoice."
    },
    "model_output": {
      "company": "Acme Corp"
    },
    "trace_config": {
      "model": "gpt-4o",
      "internal_run_id": "run_01j2abcde"
    }
  }'

Response 201 returns a trace object. The most important fields for integrations are:

Field	Meaning
`id`	Store this if you want to fetch the trace later.
`status`	Starts as `pending`; later becomes `approved`, `rejected`, or `corrected`.
`model_input` / `model_output`	The original payloads you sent.
`corrected_output`	Reviewer-edited output, present after a correction.
`final_output`	The authoritative result: original output if approved, corrected output if corrected, `null` if rejected or still pending.
`trace_config`	Your metadata, round-tripped unchanged.
`tags`	Tags attached to the trace.
`version`	Optimistic-lock version for advanced lifecycle writes.

Read review results¶

`GET /v1/traces/{trace_id}`¶

Fetch one trace by ID. Use this when your system wants to poll for the final review outcome.

curl "https://api.tuor.dev/v1/traces/trace_abc123" \
  -H "X-API-Key: $TUOR_API_KEY"

`GET /v1/traces/`¶

List traces with pagination and filters.

Parameter	Type	Notes
`project_id`	string	Restrict to one project.
`status`	`pending` \| `approved` \| `rejected` \| `corrected`	Filter by review outcome.
`tag`	string	Restrict to traces carrying this tag ID.
`skip`	int	Offset for pagination. Default `0`.
`limit`	int	Page size. Default `50`, max `500`.

Export reviewed data¶

`GET /v1/traces/export`¶

Streams one JSON object per line. Use this for offline evals, dashboards, prompt analysis, or training-data jobs.

Parameter	Type	Notes
`project_id`	string	Restrict to one project.
`status`	string	Commonly `approved` or `corrected` for training/eval datasets.
`tag`	string	Restrict to traces carrying this tag ID.
`from_date`, `to_date`	ISO 8601	Filter by `created_at`.
`exclude_fields`	comma-separated paths	Remove direct child keys such as `model_input.pdf_base64`.

curl "https://api.tuor.dev/v1/traces/export?status=corrected&exclude_fields=model_input.pdf_base64" \
  -H "X-API-Key: $TUOR_API_KEY"

Each JSONL row includes:

{
  "model_input": { "...": "..." },
  "model_output": { "...": "..." },
  "corrected_output": { "...": "..." },
  "final_output": { "...": "..." },
  "trace_config": { "...": "..." },
  "tags": ["critical", "q2-audit"],
  "events": [],
  "metadata": {
    "trace_id": "trace_abc123",
    "status": "corrected",
    "project_id": "proj_abc123",
    "created_at": "2026-05-20T10:00:00Z",
    "updated_at": "2026-05-20T14:19:55Z",
    "last_reviewed_at": "2026-05-20T14:19:55Z",
    "version": 2
  }
}

metadata is abbreviated above; it also carries provenance fields — last_reviewed_by, created_by, org_id, updated_by, and the deleted_*/restored_* audit columns. Treat it as an open object rather than coding against a fixed key set.

The events array contains the audit trail for teams that need provenance. Most downstream jobs can rely on status, final_output, trace_config, and tags.

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. To discover IDs, call GET /v1/tags/ and store the returned id for each tag you plan to apply.

curl "https://api.tuor.dev/v1/tags/" \
  -H "X-API-Key: $TUOR_API_KEY"

An abbreviated response includes each tag's id, name, color, and description:

[
  {
    "id": "tag_critical",
    "name": "critical",
    "color": "#ef4444",
    "description": "High-priority reviews"
  }
]

curl -X POST "https://api.tuor.dev/v1/traces/trace_abc123/tags" \
  -H "X-API-Key: $TUOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag_ids": ["tag_critical"] }'

A trace can have up to 10 tags.

Advanced¶

Most integrations do not need these endpoints on day one.

Area	Endpoints	Notes
Prompt versions	`GET /v1/projects/{project_id}/prompts`, `POST /v1/projects/{project_id}/prompts`, `POST /v1/projects/{project_id}/prompts/refine`, `POST /v1/projects/{project_id}/prompts/accept-refinement`	Use when your service fetches active prompts from Tuor at runtime. See Dynamic Prompts.
Trace lifecycle automation	`POST /v1/traces/{trace_id}/review`, `POST /v1/traces/{trace_id}/reset`, `DELETE /v1/traces/{trace_id}`, `POST /v1/traces/{trace_id}/restore`	The Web Console is the normal review surface. These endpoints require `expected_version` to prevent conflicting writes.
Project and tag administration	`/v1/projects/`, `/v1/tags/`	Usually handled in the Web Console. Useful only for provisioning automation.

Error responses¶

Errors are returned as JSON:

{ "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`	API key is valid but does not have an organization context.
`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`.