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

# How the API Works

> The request lifecycle, from key to settled usage.

Your app sends one request to one endpoint with one key. Nito resolves the model and privacy level, routes to an eligible backend, reserves usage, calls the provider, and returns or streams the result.

## The Request Lifecycle

A simplified flow.

```mermaid placement="top-right" theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Client request] --> B{Auth &<br/>rate limit}
    B -->|401 / 429| R([Rejected])
    B -->|ok| F[Inference] --> G[Response] --> H{Completed?}
    H -->|success| I([Settle usage])
    H -->|failure| J([Release reservation])
```

<Steps>
  <Step title="Authenticate" icon="1" iconType="solid" stepNumber={1} titleSize="h4">
    The key in `Authorization: Bearer` resolves to your organization. Missing, malformed, revoked, or expired keys get `401`. Over a rate limit you get `429` with `Retry-After` and `X-RateLimit-*` headers.
  </Step>

  <Step title="Resolve" iconType="solid" stepNumber={2} titleSize="h4">
    The `model` field selects the model; the catalog entry carries its privacy level. A `:confidential` suffix asks for the attested variant. A model that cannot serve what you asked for is rejected, never downgraded.
  </Step>

  <Step title="Route" icon="3" iconType="solid" stepNumber={3} titleSize="h4">
    One logical model may have several physical routes. Nito filters by privacy level and the features you sent, then picks a healthy one.
  </Step>

  <Step title="Reserve" icon="4" iconType="solid" stepNumber={4} titleSize="h4">
    Expected usage is reserved against your organization before the provider call. Nothing is charged yet.
  </Step>

  <Step title="Run" icon="5" iconType="solid" stepNumber={5} titleSize="h4">
    Nito calls the provider at the selected level and returns one response or a token stream.
  </Step>

  <Step title="Settle" iconType="solid" stepNumber={6} titleSize="h4">
    On success the reservation settles for actual usage. A request that fails before producing usage releases it.
  </Step>
</Steps>

## Public Model Catalog

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.trynito.ai/v1/models
```

Model discovery is public. Inference requires an API key and account eligibility.

Each entry carries the `id` you send back, its `type`, capability flags (`supports_reasoning`, `supports_image_inputs`, `supports_web_search`, and more), and its `privacy_tier`. The catalog changes over time; treat `GET /v1/models` as the live source and select by capability at runtime. IDs are `vendor/model`, for example `openai/gpt-5.5` or `moonshotai/kimi-k3`. See [Model ID Convention](/models/model-id-convention).

## Level by Model ID

| You send | Level | Meaning |
| - | - | - |
| A frontier model, for example `anthropic/claude-sonnet-5` | Anonymous | The provider receives the request from Nito, under Nito's account, without your identity attached. The optional `user` field is forwarded when the provider supports one, so keep identifying values out of it. |
| An open-weight model, for example `z-ai/glm-5.2` | Private | Zero data retention enforced upstream. |
| `z-ai/glm-5.2:confidential` | Confidential | Runs inside sealed hardware. Nito fetches attestation evidence before the call and fails closed without it. Fetch evidence bound to your own challenge from `GET /api/v1/attestation`. |
| `:encrypted` | Encrypted | Confidential plus encryption of the prompt on your device, with the Encrypted headers. See [Encrypted](/api/api-reference/chat-and-text/encrypted). |

Available levels appear as separate model IDs and `privacy_tier` values in the catalog. Nito stores nothing you send or receive at any level. See [Privacy Levels](/privacy/levels).

The only suffixes are `:confidential` and `:encrypted`. There is no privacy field in the request body, and a level never downgrades: a model that cannot serve it returns an error before any provider call.

## What One Key Covers

* Chat at `/v1/chat/completions` (OpenAI shape) and `/v1/messages` (Anthropic shape).
* Web search and web fetch, run by Nito before the model call.
* File input: PDFs and office documents parsed into text.
* Reasoning, with effort and summary controls.

Each has a page under [Features](/api/features).

## Two Rules

* **No fallback.** A `:confidential` call that cannot be served as asked fails.
* **Routes can vary.** The same logical model may run on different eligible backends across calls. For Confidential calls, the attestation evidence names what ran.

## Next

<CardGroup cols={3}>
  <Card title="Quickstart" icon="play" href="/api/get-started/quickstart-60-seconds">
    A first request.
  </Card>

  <Card title="Authentication" icon="key" href="/api/get-started/authentication">
    Keys and headers.
  </Card>

  <Card title="Privacy Overview" icon="shield-check" href="/privacy/overview">
    The four levels and attestation.
  </Card>
</CardGroup>


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