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

# How it works

> One endpoint, one key, one extra field. What happens to a call after it leaves your app.

Protégé is a managed API. You do not bring provider keys or host models: every
model is served on our capacity, so there is one key and one bill.

## The request path

```mermaid theme={null}
flowchart LR
  A["Your app"] -->|"task + messages"| B["api.protege.sh<br/>/v1/chat/completions"]
  B --> C{"Route for<br/>this task?"}
  C -->|"approved route"| D["Specialist model"]
  C -->|"none yet"| E["Default model"]
  D --> F["Response<br/>+ protege block"]
  E --> F
  F --> A
  B -.->|"trace"| G[("Task history")]
```

Every call carries a `task`. The label decides which route serves it, and the
same label files the trace under that task. A task with no approved route yet
falls through to your default model, so labelling is always safe to add.

## What a task accumulates

```mermaid theme={null}
flowchart LR
  A["Unlabelled<br/>calls"] -->|"add task"| B["Measured<br/>cost per task"]
  B -->|"define correct"| C["Eval contract"]
  C -->|"cheaper model clears it"| D["Routed down"]
  C -->|"nothing clears it"| E["Train a<br/>specialist"]
  E --> D
```

Each step is worth something on its own. Measurement alone usually reshuffles
what a team thinks is expensive. Most tasks stop at **Routed down**, because an
existing cheaper model turns out to be good enough once someone defines what
good means.

## Why a route is never promoted on price

```mermaid theme={null}
flowchart TD
  A["Candidate model"] --> B{"Clears the task's<br/>eval contract?"}
  B -->|"no"| C["Rejected"]
  B -->|"yes"| D{"Cheaper than<br/>the incumbent?"}
  D -->|"no"| C
  D -->|"yes"| E["Proposed to you"]
  E --> F{"You approve"}
  F -->|"no"| C
  F -->|"yes"| G["Serves auto traffic"]
```

Price only breaks ties among candidates that already pass. Without a contract on
a workload there is nothing to gate on, so it stays on the model you name
rather than guessing.

Nothing reaches production traffic without a human accepting it, and every
promotion is versioned and reversible.

## What you manage, and what we do

| You                       | Protégé                                     |
| ------------------------- | ------------------------------------------- |
| Send labelled calls       | Serves them on managed capacity             |
| Name the tasks            | Measures cost, latency and quality per task |
| Define what correct means | Scores candidates against it                |
| Approve a route change    | Proposes it, versions it, rolls it back     |

<Note>
  Managed only for now. There is no bring-your-own-key or self-hosted option, so
  there are no provider accounts to configure and no upstream credentials to
  pass through.
</Note>

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/quickstart">
    First labelled call in four steps.
  </Card>

  <Card title="Tasks" icon="scissors" href="/concepts/projects-and-workloads">
    Naming and granularity, the part that decides whether any of this works.
  </Card>
</CardGroup>