API Reference
OrchVynt exposes an HTTP API for routing invocations and managing configuration. All requests use JSON bodies. Authentication is via bearer token (your OrchVynt API key).
Authentication
All API calls require an Authorization: Bearer <api_key> header. Your API key is available in the OrchVynt dashboard after sign-up.
Base URL
Cloud-hosted: https://api.orchvynt.com/v1
Self-hosted: http://<your-host>:4821/v1
POST /route
Route an agent invocation through the control plane. OrchVynt applies routing policy, enforces budgets, evaluates HITL gates, and proxies the request to the selected model provider.
POST
/v1/route
Request body
Request (JSON)
{
"workload": "synthesis",
"messages": [
{"role": "user", "content": "Summarize this document."}
],
"context": {
"user_tier": "premium",
"session_id": "sess_abc123"
},
"options": {
"temperature": 0.7,
"max_tokens": 2048
}
}
Response body
Response (JSON)
{
"content": "The document discusses...",
"model_used": "gpt-4o",
"provider_used": "openai",
"routing_decision": {
"policy_matched": "workload:synthesis",
"fallback_tier_used": null
},
"usage": {
"prompt_tokens": 412,
"completion_tokens": 186,
"total_cost_usd": 0.0024
},
"invocation_id": "inv_7f3b2e1a"
}
Error codes
| HTTP status | Code | Meaning |
|---|---|---|
| 400 | invalid_request |
Malformed request body or missing required fields |
| 401 | unauthorized |
Missing or invalid API key |
| 402 | budget_exceeded |
Invocation rejected — per-workflow or per-session budget exhausted |
| 503 | all_providers_failed |
All fallback tiers failed — no provider returned a success response |
| 202 | hitl_pending |
HITL gate triggered — invocation is pending human review; poll for resolution |
The full config schema reference (all YAML fields for routing, fallback, budgets, HITL, and telemetry) is available in the OrchVynt dashboard once you sign up for early access.