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

# Getting Started

> Create a project, get an API key, and send your first trace.

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

> [!NOTE]
>
> You need a Tuor account with access to at least one organization. Sign up at [tuor.dev](https://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](https://docs.tuor.dev/guides/reviewer-blueprints.md) 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. Only **organization admins** can create them.

1. Open **Settings → API Keys** in the Web Console.
2. Click **Create New 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 a key from the same panel; revoked keys stop working immediately.

## Send your first trace

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

The simplest possible ingest:

```bash theme={null}
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 Python theme={null}
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()
```

```ts TypeScript theme={null}
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?

* Get familiar with the **[trace data model and lifecycle](https://docs.tuor.dev/core-concepts.md)** before wiring Tuor into production traffic.
* The **[Integration API](https://docs.tuor.dev/reference/api-reference.md)** documents trace ingest, fetching, tagging, and export.
* If you want corrections to flow back into your system in real time, set up an **[outbound webhook](https://docs.tuor.dev/reference/webhooks.md)**.


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