Routing and trust

Catalog filters

GET /v1/models is public and cursor-paginated. Filters compose with AND semantics; repeated values are not accepted.

Exact tier, minimum tier, and confidentiality

attestation_tier is exact. min_attestation_tier accepts that tier or a higher one. T1 is a verified software report; T2 adds hardware device identity; T3 is confidential hardware; T4 is an admin-KYB identity tier. Tier order alone does not imply prompt confidentiality, so use prompt_confidential when that property is required.

With live=true, capability, tier, provider and confidentiality filters inspect only routes that can dispatch now. Without it, a result may be registered but 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.

Provider preference and failover

X-Mayhem-Prefer-Providers is strict, not a hint. Providers are tried in the supplied order, and the request fails with preferred_provider_unavailable when none qualifies. OpenMayhem never silently falls back outside the list.

Tier, context, quantization, throughput and price constraints apply to every retry, failover and hedge candidate. Hedging does not weaken those constraints and cannot be combined with a strict preferred-provider list.

Asynchronous jobs

Routing headers are captured as immutable asynchronous-job evidence at creation. Idempotent replays must match those stored requirements, and they remain attached during reconciliation. Poll and artifact requests do not need the headers again; later changes cannot mutate the job.

Retail cost versus wholesale routing price

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. It is an exact decimal USD string, not a floating-point estimate.

Examples

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": "Summarize this contract."}],
    "max_tokens": 1000
  }'

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-Mayhem-Min-Tok-S": "20",
      "X-OpenMayhem-Max-Cost-Usd": "0.50",
    },
    body: JSON.stringify({
      model: "qwen/qwen3.8-27b",
      messages: [{ role: "user", content: "Give me three release risks." }],
      max_tokens: 800,
    }),
  },
);

if (!response.ok) throw new Error(await response.text());
const completion = await response.json();

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-Prefer-Providers": "PROVIDER_PUBLIC_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,
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())

Stable constraint errors

Invalid values and unavailable combinations fail before spend with stable codes. Recheck the live catalog before changing the constraint or retrying. See Errors for the complete code catalog. Errors.