# Proxy models Proxy providers connect their existing language or decision models to OpenMayhem. They set individual prices and remain separate from calibrated models. Names and categories describe provider claims; they do not verify the model's weights. ## Discover offers Open Proxy Models to browse categories, families and individual offers. Filter by endpoint, context and payment currency. Read the selected offer's input contract for that currency before building a request. A listed offer does not reserve capacity; missing or expired health evidence is not availability. Directory: https://openmayhem.ai/proxy-models Public API reads (base URL https://api.openmayhem.ai): - GET /v1/proxy/offers?limit=25 - GET /v1/proxy/offers/{market}/{provider}/{slot} - GET /v1/proxy/offers/{market}/{provider}/{slot}/contract?rail=fiat - GET /v1/proxy/category-offers?category={URL-encoded-category-reference}&limit=25 - GET /v1/proxy/taxonomy/releases/current - GET /v1/proxy/taxonomy/releases/{release_id}/entries?kind=category&limit=25 Ordinary offer filters are kind (llm/decision), family_id, name_prefix, endpoint, minimum_context and rail (fiat/tnk/tap). Endpoint values are openai_chat_completions, openai_completions, openai_responses or mayhem_decisions. The model selector is proxy/offer/{market}/{provider}/{slot}; use the exact identifiers from discovery. A display name is not a routing identifier. A category reference contains entry_id, schema_revision, release_id and release_hash from the published taxonomy. JSON-encode that object as the category query parameter. Keep the same reference and filters on continuation requests. Exact-model queries use the model parameter with the JSON-encoded family_id/model_id/revision/quantization tuple. Do not substitute only its name. ## Save your routing choices Create a profile on the website or in Studio. Choose an exact offer, model or category, allowed providers, verification requirements, context, controls and explicit price/spending limits. A category may choose among compatible providers; an exact model never silently expands to its family. Save once and reuse the profile's version. API and MCP can read and resolve profiles, but cannot create or edit your spending policy. Profiles can also require typed capabilities, controls and data-handling evidence. Unsupported or unproven requirements are rejected rather than ignored. Provider verification and reported model identity are separate. Choosing a profile does not prove that a compatible offer is currently free. ## Use the API Create an API key with PROFILE and the required endpoint scope. Read a saved profile, then start resolution with its version, one allowed currency and the complete request. If pending, respect retry_after_ms and continue with the returned token. A selected result contains an exact request and estimate. Send that unchanged to the matching paid endpoint within your cost limit. Resolution and estimates do not reserve capacity or authorize payment. API keys are created in the OpenMayhem dashboard. Keep them on your server or in your agent's secret configuration, not in browser code. Read account-owned profiles with GET /v1/proxy/profiles and GET /v1/proxy/profiles/{id}?version=1. Begin POST /v1/proxy/profiles/{id}/resolve with this example for a compatible chat profile (substitute the actual version and an authorized currency): ```json {"kind":"start","version":1,"rail":"fiat","request":{"messages":[{"role":"user","content":"Hello"}],"max_tokens":128}} ``` For pending selection, POST {"kind":"continue","continuation":""} to the same resolve route, observing retry_after_ms. Do not edit the token or silently change the original input. selected/retained_compatible results contain the actual supplier, exact materialized request, currency and estimate. no_match, incomplete or refresh_required are not executable selections. The execution endpoints are POST /v1/chat/completions, /v1/completions, /v1/responses and /v1/decisions. Select only the endpoint supported by the chosen contract. Preserve the returned model, proxy controls, profile binding and input. Existing API authentication and estimate/maximum-cost controls still apply. The effective limit is the tightest of the saved profile, key and request limits. Never invent prices, a settlement policy hash or a currency to make admission pass. Use a unique Idempotency-Key per independent paid invocation and retain it across retries of that identical invocation. An uncertain dispatch is not evidence that nothing ran: look up the original job/request. A fresh key may create a new charge. Streaming and non-streaming remain subject to the selected endpoint contract. ## Use Studio Choose the Proxy tab in the model picker and select a saved chat profile and payment currency. Each turn records its actual supplier. Native chats need the explicit proxy-tools setting before calling proxy profiles. Child tasks inherit their parent's limits. Automatic fallback does not cross into calibrated models or change currency. Studio list_models stays native by default. With lane: "proxy" it discovers profiles/offers; metadata_kind: "category" returns category_targets. Pass a target's taxonomy object as category in a later proxy list_models call. Continue offer_cursor separately from profile pagination. get_model reads an offer's actual input contract. call_model can use an authorized saved chat or decision profile. Discovery cannot enable proxy tools or enlarge delegated permissions. ## Use MCP Discover with list_proxy_models, inspect get_proxy_model with an explicit rail, and read list_proxy_profiles/get_proxy_profile. Use prepare_proxy_profile for a chosen offer or resolve_proxy_profile for automatic selection within your saved rules. Pass the returned request and estimate to the matching chat, complete_text, create_response or decide tool. Discovery alone is not permission to spend. - list_proxy_metadata with kind: "category" returns category_targets. - Pass a target's taxonomy object as category to list_proxy_models, or list_models with lane: "proxy". Native discovery rejects that proxy-only filter. - get_proxy_model takes model: "proxy/offer/..." and an explicit rail to return the executable input contract. A category itself has no single request schema. - prepare_proxy_profile takes profile_id, version, model, rail and request. - resolve_proxy_profile starts with profile_id, version, rail and request; continue with profile_id, version and the returned continuation. - Paid tools take the exact model/request, estimate_id and an authorized max_cost_usd. Reuse the original idempotency_token for retries of that invocation. Proxy inference supports only language and decision endpoints. Native image, video, embedding, audio and workflow tools retain their existing contracts; an explicit authorized native tool call is separate from proxy routing fallback. ## Connect an existing model Core must stay running as the controller. Use its proxy setup flow to discover a compatible endpoint or import a reviewed connector recipe, declare capabilities, run bounded checks, set prices and obtain admission. The one-time $10 admission fee accepts the enabled FIAT, TNK or TAP method; it is separate from inference credit. Publication requires independently verified payment. Keep upstream credentials in the protected local connection configuration, never in public metadata. Observed capabilities and declared capabilities are distinct. A connector cannot advertise unsupported streaming, tools or structured output as working. Core's controller reports loss of readiness and capacity, and performs bounded recovery. If other applications use the same upstream, share capacity information when available; without exclusive upstream reservations availability is best effort, not a promise that another consumer cannot take the final slot. ## Prices, trust and recovery Providers set fixed offer rates; proxy prices do not use the calibrated 25–400% band. The accepted offer and currency remain attached to the request. Buyer, key and task limits can only narrow the saved authorization. Operator verification does not prove model weights. Busy, unavailable or unsupported requests do not relax your filters. If an accepted request becomes uncertain, check its original job instead of starting a new purchase. Accepted rates remain attached to existing work after a later offer revision or withdrawal. Reservations and settlement are bound to the original request and currency; no silent conversion or substitution of FIAT, TNK and TAP is authorized. The retail estimate includes the platform's pricing and rounds consistently with billing. Do not treat a raw provider unit price as the complete retail total. ## Pagination and updates Keep the original category release and filters when following cursors, including empty pages with a continuation. A 409 cursor-expired result means restart browsing; it does not cancel an accepted job. Category lists are grouped by membership and model name, not global price order. There is no total offer limit; each page and visible refresh is bounded. Each directory page is limited to 1–100 offers. Follow next_cursor or previous_cursor; from_end=true starts at the last page and cannot accompany a cursor. Category queries read one bounded membership page and one Core offer page per call. A missing category returns 404 proxy_category_not_found; invalid input returns 400 invalid_request_error. Changed catalog snapshots return 409 proxy_directory_cursor_expired. Preserve the selected identity while restarting browsing; changed discovery does not rewrite accepted jobs.