Skip to content

Getting Started

This guide walks you from zero to a first trace appearing in the Web Console in about five minutes.

Prerequisite: a Tuor account with access to at least one organization. Sign up at tuor.dev.

Create a project

Projects are the unit of organization in Tuor. Every trace belongs to exactly one project; each trace's self-describing spans control how its trajectory renders.

In the Web Console:

  1. Open the Projects tab in the top navigation.
  2. Click Create Project.
  3. Give it a name (1-100 characters).
  4. Open the project and copy its ID from the Config tab (IDs look like proj_aB3x…). You will use this as project_id in every ingest request.

The output is always structured JSON rendered as an editable path form. Each trace can describe its own field controls in output_schema — enum label pickers, boolean toggles, or json blocks — while paths you leave out get a control inferred from the value's type. There's no project-level output type to choose. See Reviewer Blueprints for the payload recipes.

Get an API key

API keys authenticate programmatic traffic from your services to Tuor. They are scoped to the organization that issued them.

  1. Open Settings -> API Keys in the Web Console.
  2. Click Create API Key and give it a name (e.g. production-ingest, staging).
  3. Copy the key shown on screen — it starts with tuor_ and is shown only once. Store it in your secret manager.

Keys never expire on their own. Revoke any key from the same panel; revoked keys reject all requests immediately.

Send your first trace

Replace proj_abc123 with the project ID you copied from the Web Console.

The simplest possible ingest:

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",
    "spans": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "text", "value": "What is the capital of France?"}
        ]
      },
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {"type": "text", "value": "Paris"}
        ]
      }
    ],
    "model_output": {
      "answer": "Paris"
    },
    "trace_config": {
      "model": "gpt-4o",
      "temperature": 0.0
    }
  }'

A successful response returns a TraceDetailResponse with the new trace's id, status (pending), timestamps, structured tag summaries, and event timeline. The trace should appear immediately on the Traces page for the corresponding project in the Web Console.

Tip: keep spans in the same order as the original model trajectory. Tuor preserves assistant messages even when they repeat the structured model_output review target.

Call Tuor from application code

Call the API directly from your service code and keep the API key in your server-side secret manager.

Python

import os
import httpx

TUOR_API_KEY = os.environ["TUOR_API_KEY"]

trace = httpx.post(
    "https://api.tuor.dev/v1/traces/",
    headers={"X-API-Key": TUOR_API_KEY},
    json={
        "project_id": "proj_abc123",
        "spans": [{
            "type": "message",
            "role": "user",
            "content": [{"type": "text", "value": "Compute net income"}],
        }],
        "model_output": {"amount": 250_000},
        "trace_config": {"model": "gpt-4o", "internal_run_id": "run_01j..."},
    },
    timeout=10,
)
trace.raise_for_status()

TypeScript

const response = await fetch("https://api.tuor.dev/v1/traces/", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TUOR_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project_id: "proj_abc123",
    spans: [{
      type: "message",
      role: "user",
      content: [{ type: "text", value: "Compute net income" }],
    }],
    model_output: { amount: 250_000 },
    trace_config: { model: "gpt-4o", internal_run_id: "run_01j..." },
  }),
});

if (!response.ok) throw new Error(await response.text());
const trace = await response.json();

Where next?