# Routing and trust

Discover routes by capability, then place explicit bounds on the provider
selected for a paid request. Omit every routing header to retain normal
marketplace selection and existing client behavior.

## Catalog filters

`GET https://api.openmayhem.ai/v1/models` is public and cursor-paginated. Filters compose with
AND semantics; repeated values are rejected.

| Query parameter | Type | Meaning |
| --- | --- | --- |
| `live` | boolean | When true, inspect routes that can dispatch now; otherwise inspect registered capabilities. |
| `endpoint_family` | enum | One of CHAT, COMPLETIONS, RESPONSES, EMBEDDINGS, IMAGES, VIDEOS, AUDIO_SPEECH, AUDIO_TRANSCRIPTIONS, AUDIO_GENERATIONS, MUSIC or WORKFLOWS. |
| `modality` | enum | text, embedding, image, video, audio, music or workflow. |
| `attestation_tier` | integer 1–4 | Exact tier. Mutually exclusive with `min_attestation_tier`. |
| `min_attestation_tier` | integer 1–4 | This tier or higher. Mutually exclusive with `attestation_tier`. |
| `max_input_price_per_million_usd` | decimal string | Maximum retail input price in USD per one million tokens; at most 18 decimal places. |
| `max_output_price_per_million_usd` | decimal string | Maximum retail output price in USD per one million tokens; at most 18 decimal places. |
| `max_representative_request_price_usd` | decimal string | Maximum unit-aware retail cost of the catalog's representative request; at most 18 decimal places. |
| `min_context_tokens` | integer | Minimum context capacity in tokens. |
| `quantization` | string | Canonical bucket such as bf16, nvfp4 or int4. |
| `tools` | boolean | Require or exclude native tool calls. |
| `structured_output` | boolean | Require or exclude structured JSON output. |
| `provider` | 64-hex string | Restrict models to one provider public key. |
| `prompt_confidential` | boolean | Require or exclude prompt-confidential compute. |
| `sort` | enum | id, providers, input_price, output_price, request_price, context or listed. request_price uses the unit-aware representative request cost. |
| `order` | enum | asc or desc. |
| `limit` | integer | Page size, 1–100; default 50. |
| `cursor` | string | Opaque cursor from the previous response; never construct or modify it. |

The response is `{ object: "list", data: [...], next_cursor }`. Each model
includes registered and live attestation tiers and quantizations, provider
ids with live state, tier labels, public KYB evidence, sanitized attestation
readiness, prompt-confidential availability, aggregate context and concurrency
capacity, and exact atto-USD pricing. Pass `next_cursor` back as
`cursor` with the same filters and sorting to continue.

Example:

`GET https://api.openmayhem.ai/v1/models?live=true&min_attestation_tier=2&quantization=nvfp4&max_output_price_per_million_usd=0.50&sort=output_price&order=asc&limit=25`

### Exact tier, minimum tier, and confidentiality

`attestation_tier` is exact. `min_attestation_tier` accepts the requested
tier or any higher tier. T1 is a verified software report; T2 adds hardware
device identity; T3 is confidential hardware; T4 is an admin-KYB identity
tier. Higher is not synonymous with prompt confidentiality, so filter
`prompt_confidential=true` when that property is required.

With `live=true`, capability, tier, provider and confidentiality filters
inspect only routes that can dispatch now. Without it, a model can match
because it is registered even while its provider is temporarily offline.

## Per-request routing headers

Tier, quantization, provider, throughput, wait, and retail-cost controls apply
to every paid endpoint. Context and hedging apply only to text generation.
Throughput uses each endpoint's native measured unit. Every supplied value is
validated before provider spend.

| Header | Value | Effect |
| --- | --- | --- |
| `X-Mayhem-Min-Att-Tier` | T1–T4 | Minimum provider tier; higher tiers also qualify. |
| `X-Mayhem-Min-Ctx` | positive integer | Text generation only. Minimum context capacity in tokens. The calculated input plus output need remains the effective floor. |
| `X-Mayhem-Quant` | canonical string | Require one quantization bucket. |
| `X-Mayhem-Prefer-Providers` | comma-separated 64-hex keys | Strict ordered provider set; failover never leaves the set. Maximum 64 keys. |
| `X-Mayhem-Hedge` | 0 or 1 | Text generation only. Request hedged dispatch across eligible routes; incompatible with a preferred-provider list. |
| `X-Mayhem-Min-Tok-S` | positive number | Minimum sustained throughput in the endpoint's native measured unit per second. |
| `X-Mayhem-Max-Wait-Ms` | integer 0–60000 | Provider-admission wait; not the generation or async-job runtime limit. |
| `X-OpenMayhem-Max-Cost-Usd` | decimal USD string | Maximum retail hold for this request, checked before spend; at most 6 decimal places. |

### Provider preference, failover, and hedging

`X-Mayhem-Prefer-Providers` is strict, not a hint. Providers are tried in
the supplied order. If none is currently eligible, the request fails with
`preferred_provider_unavailable`; OpenMayhem does not silently use a
provider outside the list.

Tier, context, quantization, throughput and price constraints apply to every
retry, failover and hedge candidate. Hedging never weakens those constraints.
Because preferred providers form a strict ordered set, they cannot be combined
with hedging.

### Asynchronous jobs

Routing headers are captured as immutable async-job evidence at creation.
Idempotent replays must match those stored requirements, and the requirements
remain attached during reconciliation. Do not resend them while polling or
fetching artifacts; later header changes cannot mutate the job.

## Retail max cost is not a wholesale route ceiling

`X-OpenMayhem-Max-Cost-Usd` limits the customer's worst-case retail hold.
The stricter of this value and the API key's per-request cap wins. Values are
exact decimal USD strings, not binary floating-point estimates.

`X-Mayhem-Max-Price-Au` is the platform's private wholesale rate-basis gate: a
standardized 1,000-unit basket of every priced dimension, or the fixed-price
fallback. It is not a request-total ceiling. Hosted customers must never send
or control it; the hosted API does not expose or forward it.

## curl

```bash
curl https://api.openmayhem.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENMAYHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Mayhem-Min-Att-Tier: T2" \
  -H "X-Mayhem-Min-Ctx: 131072" \
  -H "X-Mayhem-Quant: nvfp4" \
  -H "X-Mayhem-Max-Wait-Ms: 30000" \
  -H "X-OpenMayhem-Max-Cost-Usd: 0.50" \
  -d '{"model":"qwen/qwen3.8-27b","messages":[{"role":"user","content":"Hello"}],"max_tokens":500}'
```

## JavaScript

```javascript
const response = await fetch("https://api.openmayhem.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENMAYHEM_API_KEY}`,
    "Content-Type": "application/json",
    "X-Mayhem-Min-Att-Tier": "T2",
    "X-Mayhem-Hedge": "1",
    "X-OpenMayhem-Max-Cost-Usd": "0.50",
  },
  body: JSON.stringify({model: "qwen/qwen3.8-27b", messages: [{role: "user", content: "Hello"}], max_tokens: 500}),
});
if (!response.ok) throw new Error(await response.text());
```

## Python

```python
import os
import requests

response = requests.post(
    "https://api.openmayhem.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENMAYHEM_API_KEY']}",
        "X-Mayhem-Min-Att-Tier": "T2",
        "X-Mayhem-Max-Wait-Ms": "30000",
        "X-OpenMayhem-Max-Cost-Usd": "0.50",
    },
    json={"model": "qwen/qwen3.8-27b", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 500},
)
response.raise_for_status()
```

## Stable constraint errors

Invalid values and incompatible constraints fail before spend. A valid
constraint with no matching live provider returns a stable availability code
with `retryable: false`; query the live catalog before changing the constraint
or retrying. Temporary market-wide `capacity_unavailable` is retryable. See
the Errors page for the complete catalog.