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, and a project's input/output types control how reviewers see that trace.

In the Web Console:

  1. Open Settings -> Projects.
  2. Click Create Project.
  3. Give it a name (1-100 characters).
  4. Copy the generated project ID from the project's ID column (IDs look like proj_aB3x…). You will use this as project_id in every ingest request.

New projects start with text input and key_value output. To change the reviewer experience, click Edit on the project and update:

  • Input type - controls how the review workspace renders the data your model receives:
    • text — prompts, messages, or any unstructured input. Rendered as a high-density, multi-line viewer.
    • pdf — base64-encoded PDF documents. Rendered as a scrollable PDF pane.
    • image — base64-encoded images. Rendered as an image viewer.
  • Output type - controls the correction editor:
    • key_value — flat dictionary, rendered as an editable spreadsheet-like form.
    • text — long-form text, rendered as an editable text panel with word/character counts.
    • classification — single-label prediction with alternatives, rendered as a label selector with custom-label entry.

You can change these later by editing the project, but the project setting controls how all of its traces render. Only change types when existing traces already have payloads compatible with the new viewer/editor.

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",
    "model_input": {
      "content": "What is the capital of France?"
    },
    "model_output": {
      "answer": "Paris"
    },
    "trace_config": {
      "model": "gpt-4o",
      "temperature": 0.0
    }
  }'

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

Tip: putting your model's main prompt in model_input.content makes the review workspace render it as a readable, full-width text block. See the Reviewer Blueprints page for the rendering conventions per project type.

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",
        "model_input": {"content": "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",
    model_input: { content: "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?