{"name":"Host.Rodeo","summary":"Agent-first LLM gateway — one OpenAI-compatible token, auto-routed to the fit-for-purpose source (free -> local/customer-owned -> paid), always fulfilled, savings proven per call.","api":{"base":"/v1","compatible_with":"openai","auth":"Bearer token"},"integration":{"canonical_base_url":"https://api.host.rodeo/v1","console_url":"https://host.rodeo","default_model":"auto","minimum_chat_call":{"method":"POST","endpoint":"/v1/chat/completions","headers":{"Authorization":"Bearer $KEY","Content-Type":"application/json"},"body":{"model":"auto","messages":[{"role":"user","content":"hi"}]}},"client_posture":["read /v1/contract during deploy/startup instead of hardcoding capabilities","send model='auto' unless a specific model pin is intentional","use X-Rodeo-Sensitivity for private data and X-Rodeo-Prefer for latency/quality/cost bias","log X-Rodeo-* receipt headers for savings, source, tier, custody, and fallback proof","register /v1/webhooks for capability.changed and signal.resolved instead of polling"]},"generated_at":1782939778,"uptime_s":9459,"health":{"sources_total":21,"sources_available":21},"modalities":{"chat":{"endpoint":"/v1/chat/completions","sources":21},"embedding":{"endpoint":"/v1/embeddings","sources":7,"stable":true,"default_model":"baai/bge-m3","models":["Qwen/Qwen3-Embedding-0.6B","Qwen3-Embedding-8B","alibaba/qwen3-embedding-0.6b","alibaba/qwen3-embedding-4b","alibaba/qwen3-embedding-8b","amazon/titan-embed-text-v2","baai/bge-m3","bge-m3","bge-multilingual-gemma2","codestral-embed","codestral-embed-2505","cohere/embed-v4.0","embed-english-light-v3.0","embed-english-light-v3.0-image","embed-english-v3.0","embed-english-v3.0-image","embed-multilingual-light-v3.0","embed-multilingual-light-v3.0-image","embed-multilingual-v3.0","embed-multilingual-v3.0-image","embed-v4.0","google/gemini-embedding-001","google/gemini-embedding-2","google/text-embedding-005","google/text-multilingual-embedding-002","mistral-embed","mistral-embed-2312","mistral/codestral-embed","mistral/mistral-embed","models/gemini-embedding-001","models/gemini-embedding-2","models/gemini-embedding-2-preview","nvidia/embed-qa-4","nvidia/llama-3.2-nemoretriever-1b-vlm-embed-v1","nvidia/llama-3.2-nv-embedqa-1b-v1","nvidia/llama-nemotron-embed-1b-v2","nvidia/llama-nemotron-embed-vl-1b-v2","nvidia/nv-embed-v1","nvidia/nv-embedcode-7b-v1","nvidia/nv-embedqa-e5-v5","nvidia/nv-embedqa-mistral-7b-v2","openai/text-embedding-3-large","openai/text-embedding-3-small","openai/text-embedding-ada-002","snowflake/arctic-embed-l","voyage/voyage-3-large","voyage/voyage-3.5","voyage/voyage-3.5-lite","voyage/voyage-4","voyage/voyage-4-large","voyage/voyage-4-lite","voyage/voyage-code-2","voyage/voyage-code-3","voyage/voyage-finance-2","voyage/voyage-law-2"],"note":"embeddings are STABLE — pin a model for a FIXED vector dimension; 'auto' resolves to default_model deterministically (never drifts) and fails over only within the same model. The response header X-Rodeo-Embedding-Dim reports the dimension."},"rerank":{"endpoint":"/v1/rerank","sources":2},"image":{"endpoint":"/v1/images/generations","sources":7},"audio_speech":{"endpoint":"/v1/audio/speech","sources":4},"audio_transcription":{"endpoint":"/v1/audio/transcriptions","sources":5},"moderation":{"endpoint":"/v1/moderations","sources":9}},"chat_capabilities":{"tools":{"proven_by_sources":15},"json":{"proven_by_sources":15},"vision":{"proven_by_sources":5},"stop":{"proven_by_sources":12},"streaming":{"proven_by_sources":15},"logprobs":{"proven_by_sources":6},"n":{"proven_by_sources":6}},"routing":{"ladder":"free -> local/customer-owned -> paid","invisible_failover":true,"fidelity":"full OpenAI param pass-through; capable-source preference for soft params; unhonored soft params disclosed via X-Rodeo-Unhonored-Params; responses normalized to canonical OpenAI shape regardless of source"},"enrichment":{"summary":"Grounding, source-cited research, follow-up chips, public media lookup, and discovery feeds behind the same authenticated /v1 gateway. Clients never call Vane, SearXNG, Serper, OpenRouter, paid providers, or local/customer-owned providers directly.","auth":"Bearer token","endpoint_convention":"route endpoint values beginning with /v1 are origin-root paths; join them against https://api.host.rodeo, not by appending them to canonical_base_url","routing":{"order":"owned/self-hosted -> free/local -> controlled external fallback","owned_first":true,"external_fallback":"used only when owned search/media/model paths are empty, unavailable, or below the request bar"},"safety":["public http(s) URLs only for media and discovery assets","no file:, data:, javascript:, localhost, or private-network URLs in public responses","dedupe and cap result arrays before returning them to clients","no provider internals, prompts, embeddings, scores, stack traces, raw payloads, or model names","empty arrays are valid when no safe public asset or item is available"],"routes":{"fast_search":{"endpoint":"/v1/search","method":"POST","request":{"query":"string"},"response":{"query":"string","results":"formatted grounded result block"},"purpose":"fast grounded lookup without a model-driven research loop","degrades":"503 if the search backend is unavailable"},"research":{"endpoint":"/v1/research","method":"POST","request":{"query":"string","sources":"optional array","mode":"speed|balanced|quality","maxSources":5},"unsupported_request_fields":{"model":"model:'auto' is tolerated and ignored; pinned models return 400"},"response":{"answer":"string","sources":[{"title":"string","url":"https://...","snippet":"string"}],"citationStatus":"cited|source_linked|uncited","citationPath":"vane|owned_search|owned_search_low_confidence|external_search_fallback|uncited","synthesisPath":"native|vane","totalMs":"server-side latency in milliseconds"},"headers":{"X-Rodeo-Citation-Status":"cited|source_linked|uncited","X-Rodeo-Citation-Path":"vane|owned_search|owned_search_low_confidence|external_search_fallback|uncited","X-Rodeo-Synthesis-Path":"native|vane","X-Rodeo-Total-Ms":"server-side latency"},"purpose":"source-cited synthesis; speed/balanced use Host.Rodeo's native search-quality-gated synthesis path, quality tries the private Perplexica/Vane research path first and falls back to native when Vane is slow or unavailable","degrades":"returns a deterministic cited source digest when synthesis cannot finish; if no citations can be produced the answer is empty with citationStatus='uncited'"},"suggestions":{"endpoint":"/v1/suggestions","method":"POST","request":{"query":"string","answer":"optional string","sources":"optional source array","maxItems":4},"response":{"suggestions":["string"]},"purpose":"short follow-up question chips for product UIs","degrades":"503 when unavailable; empty array when the backend has no useful suggestions"},"public_images":{"endpoint":"/v1/images","method":"POST","request":{"query":"string","maxItems":3},"response":{"assets":[{"kind":"image","url":"https://...","sourceUrl":"https://...","title":"optional","alt":"optional"}]},"purpose":"public image lookup for venues, topics, and other public entities; not image generation","degrades":"503 when no media backend is callable; empty array when no safe public assets are found"},"public_videos":{"endpoint":"/v1/videos","method":"POST","request":{"query":"string","maxItems":3},"response":{"assets":[{"kind":"video","url":"https://...","sourceUrl":"https://...","title":"string","thumbnailUrl":"optional"}]},"purpose":"public video lookup for source-linked clips; not generated video","degrades":"503 when no media backend is callable; empty array when no safe public assets are found"},"discover":{"endpoint":"/v1/discover","method":"POST","request":{"topic":"string","city":"optional string","maxItems":5},"response":{"items":[{"title":"string","url":"https://...","source":"string","summary":"string","publishedAt":"optional"}]},"purpose":"source-linked current public items for a topic, geography, or category","degrades":"empty array when no source-linked public items are available"}}},"private_routing":{"available":true,"note":"sensitive/secret traffic routes to eligible self-hosted/customer-owned sources; fails closed (503) rather than leak"},"receipt_headers":["X-Rodeo-Source","X-Rodeo-Model","X-Rodeo-Tier","X-Rodeo-Saved-USD","X-Rodeo-Verified","X-Rodeo-Unhonored-Params","X-Rodeo-Profile","X-Rodeo-Profile-Source","X-Rodeo-Custody","X-Rodeo-Local-Source"],"control_headers":{"X-Rodeo-Sensitivity":"public|sensitive|secret (pins eligible self-hosted/customer-owned sources)","X-Rodeo-Prefer":"latency|quality|cost|balanced — latency: interactive lane, routes around slow models + fails over fast (real answer or clean 503, no 50s hang); quality: best proven model; cost: cheapest (default); balanced: weigh quality, cost, and latency together"},"account":{"profiles":["cost","quality","latency","balanced","private"],"default":"cost","descriptions":{"cost":"Cost-first - cheapest fit (free -> local/customer-owned -> paid). The default.","quality":"Quality-first - strongest proven source for the job, degrading when unavailable.","latency":"Latency-first - fastest fit, with fast failover.","balanced":"Balanced - quality, cost, and latency weighed together.","private":"Private - sensitive data stays on eligible local/self-hosted sources. Fails closed."},"set":"PUT /v1/account/prefs {\"profile\":\"private\"} ; read: GET /v1/account/prefs","note":"an ACCOUNT-level routing default applied to every request from your principal; any per-request X-Rodeo-* header overrides it. The product routing tiers are free, local, and paid; FERN is one current dogfood local source, not the product category."},"channels":{"feedback":{"endpoint":"/v1/feedback","method":"POST","auth":"none","send":{"reporter":"<your-id>","observation":"<required>","notes":"...","metrics":{}},"resolve":"GET /v1/feedback/{id}","note":"send a signal; our operator adjudicates it autonomously on our OWN models — evidence, never a command"},"webhooks":{"register":"/v1/webhooks","method":"POST","auth":"your Bearer key (self-service, no admin)","body":{"consumer_id":"<your-id, matches your reporter>","url":"<your https receiver>","events":["signal.resolved","capability.changed"]},"events_available":{"signal.resolved":"the resolution of a feedback signal YOU sent (1:1)","capability.changed":"the platform's capability surface changed (new model/modality/profile) — re-read /v1/contract. Fires only on a MATERIAL change (debounced, coalesced); never on traffic/latency."},"verify":"HMAC-SHA256(secret, raw_body) == X-HostRodeo-Signature; dedupe by event_id; ack 200","note":"self-register to be PUSHED signal resolutions + capability changes — no polling. Storm-safe: rate-limited, bounded retries, deliberate triggers only."}},"contract_version":"bd3c1bd1428768c8","quickstart":"Point any OpenAI client at this base with your Bearer key and model='auto' — it just works. Audio STT: POST /v1/audio/transcriptions (multipart). Everything you need is in THIS manifest.","laws":["this manifest never overstates — a capability is listed only if >=1 available source proves it","caller feedback is evidence, adjudicated by our own probe, never a direct command"]}