Routing and trust

Proxy models: Use proxied models like native ones in Chat, the API and MCP.

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 a strict list. 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.

Price ceilings per unit

The three price ceiling headers cap the retail price you accept for the model of the request. They take the same numbers as the max_input_price_per_million_usd, max_output_price_per_million_usd and max_representative_request_price_usd catalog filters, so one value filters the catalog and caps admission. The API compares them with the price fixed for the request, in exact integer arithmetic, before any credit is held, and refuses a higher price with 403 price_ceiling_exceeded naming the model, field, ceiling and current price. A ceiling on a unit the model does not charge for has no effect; cap media, audio, video and workflow models with the representative request ceiling.

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" \
  -H "X-OpenMayhem-Max-Output-Price-Per-Million-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",
      "X-OpenMayhem-Max-Input-Price-Per-Million-Usd": "0.20",
      "X-OpenMayhem-Max-Output-Price-Per-Million-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",
        "X-OpenMayhem-Max-Output-Price-Per-Million-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.