Admin API: providers, gears and routing
Manage an org's provider keys, gears, routing policy, venom-auto tiers, prices, model lifecycle, gear and prompt experiments, shadow tests, guardrails and prompt filters over /api/admin/v1.
These routes decide what a request to /v1 can reach and how it is served: the org's own provider keys
(sealed in the cloud's vault), its gears, its routing policy, venom-auto's tiers, prices, and the safety
layers (guardrails, prompt filters) that run on every request. Auth, scoping and the error shape are the same
as on every admin route: see Calling the admin API.
Listing routes take ?tenant=<org id> for the operator; writes take tenant_id in the body. An org member or
a key group admin key always acts on its own org. A key group holds API keys, daemons, policies and GPU grants,
not people; the API keeps the name team, so team, teams and owner below take key group ids.
Example: bring your own key and route to it
Add an OpenAI key to the org, check it lists models, then make the org serve from cloud providers first:
export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_CLOUD_ADMIN_TOKEN" # or a vak_ key
curl -s "$VENOM_CLOUD/api/admin/v1/providers" -H "$ADMIN" -H "Content-Type: application/json" \
-d '{"provider": "openai", "name": "default", "key": "sk-...", "verify": true}'
curl -s -X PUT "$VENOM_CLOUD/api/admin/v1/routing/modes" -H "$ADMIN" -H "Content-Type: application/json" \
-d '{"alias": "", "modes": ["managed", "private"], "prefer": "cheapest"}'
curl -s "$VENOM_CLOUD/api/admin/v1/routing/preview?model=gpt-5-mini" -H "$ADMIN"import os, requests
base = "https://cloud.usevenom.dev/api/admin/v1"
h = {"Authorization": f"Bearer {os.environ['VENOM_ADMIN']}"}
cred = requests.post(f"{base}/providers", headers=h, json={"provider": "openai", "key": os.environ["OPENAI_KEY"], "verify": True}).json()
print(cred["id"], cred.get("key_hint"))The key itself is never returned again: listings carry a hint (its last characters).
Provider keys
The org's own keys for cloud providers. Without VENOM_VAULT_KEYS on the deployment these routes answer
503 vault_not_configured. Supported provider ids: openai, anthropic, gemini, mistral, groq,
together, fireworks, deepseek, xai, openrouter, qwen, zai, typesafe, cerebras, deepinfra,
nebius, moonshot, minimax, siliconflow, novita, chutes, baseten, azure, vercel,
cloudflare, huggingface, portkey, requesty, martian, aimlapi, edenai, bedrock, bedrock-iam,
sagemaker, litellm, custom.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/providers |
providers:read |
The org's provider keys (hints only). ?provider= filters; ?models=1 adds each key's model listing. |
POST /api/admin/v1/providers |
providers:write |
Add a key: {provider, key, name?: "default", base_url?, priority?: 100, params?, headers?, models?, enabled_models?, verify?, tenant_id?}. priority 0 to 100,000, lower serves first. verify: true lists models first and stores nothing on a 401/403. |
POST /api/admin/v1/providers/discover |
providers:write |
Same fields, without saving: check a key and list its models (one call, 5 s at most). |
PATCH /api/admin/v1/providers/{id} |
providers:write |
{priority?, enabled?, name?, base_url?, params?, enabled_models?}. |
DELETE /api/admin/v1/providers/{id} |
providers:write |
Revoke the key. |
POST /api/admin/v1/providers/reorder |
providers:write |
{ids}: the serving order of the org's keys. |
POST /api/admin/v1/providers/{id}/check |
providers:read |
A live check, at most one models call per key per minute whoever asks. POST /api/admin/v1/providers/{id}/test (providers:write) checks and refreshes the model list. |
POST /api/admin/v1/providers/{id}/rotate |
providers:write |
{key, grace_hours?, verify?}: the new key serves first and the old one stays behind it for grace_hours (default the org's, 24; 0 retires it at once). One rotation at a time. {} re-seals the key under the vault's current key id. |
POST /api/admin/v1/providers/{id}/rotation |
providers:write |
{action: "retire" | "rollback"} during a rotation: retire the old key now, or put it back and drop the new one. |
GET /api/admin/v1/providers/{id}/versions |
providers:read |
Every key this credential held, newest first, by last four characters. |
GET /api/admin/v1/providers/status |
usage:read |
How each provider, model and target served the org's traffic: ?days=1|7|30, &key=, &daemon=. |
Whether the cloud may fall back to Venom's own platform keys is PUT /api/admin/v1/settings/platform-keys
(Org settings).
Catalog sync
Compare what a provider lists now with what the org serves and books.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/catalog-sync |
providers:read |
Each org key's last check, diffed against what the cloud serves now (?provider=). Calls no provider. |
POST /api/admin/v1/catalog-sync/check |
providers:write |
{credential_id?, provider?}: one models call per key, then the diff. |
POST /api/admin/v1/catalog-sync/apply |
providers:write |
{credential_id, actions, provider?}. Each action is {type: "add_model" | "stop_serving" | "custom_price", model}, {type: "base_model", model, base} or {type: "save_listing"}. Audited catalog_sync.applied. |
GET /api/admin/v1/catalog-sync/platform |
operator | Venom's price table against the platform keys' last listings, with a patch to paste. |
POST /api/admin/v1/catalog-sync/platform/check |
operator | One models call per platform provider, then the table diff. |
Prices
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/pricing |
providers:read |
Every model the org's cloud candidate serves: per target the effective price, its source (custom, provider, builtin), the base model it was priced as, unpriced models flagged, and daemons' own prices. The source order and custom prices are set with PUT /api/admin/v1/settings/pricing (Org settings). |
Pricing simulator
For orgs that resell to their own customers: what each customer would have paid under another price plan.
A plan is {kind: "markup", percent}, {kind: "price_list", models, other_percent},
{kind: "flat", monthly_fee, included, overage_percent} or {kind: "tiered", bands}.
| Route | Permission | What it does |
|---|---|---|
POST /api/admin/v1/pricing-simulator |
billing:read |
{plan, from?, to?, customer_ids?}: revenue, margin and the change per customer over the period, from the customer ledger. Nothing is stored. |
GET /api/admin/v1/pricing-simulator/drafts |
billing:read |
Saved plan drafts. |
POST /api/admin/v1/pricing-simulator/drafts |
billing:manage |
Save a draft to apply later. |
GET /api/admin/v1/pricing-simulator/drafts/{id} |
billing:read |
The draft, simulated again on today's ledger. |
DELETE /api/admin/v1/pricing-simulator/drafts/{id} |
billing:manage |
Discard it. |
POST /api/admin/v1/pricing-simulator/drafts/{id}/apply |
billing:manage |
{customer_ids?}: the plan becomes those customers' price rule from now on; what was booked keeps its price. Audited pricing_plan.applied. |
Model lifecycle
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/lifecycle |
providers:read |
Models the org uses that are retiring or gone, price changes seen, prepaid credits left and the settings. |
PUT /api/admin/v1/lifecycle/settings |
providers:write |
{warn_days?: 30, credits_first_days?: 0}: warn this many days (1 to 365) before a retirement; prefer keys with credits expiring within N days. |
POST /api/admin/v1/lifecycle/switch |
org:manage |
{model, replacement}: every gear naming model names replacement instead. |
POST /api/admin/v1/lifecycle/credits |
providers:write |
{credential_id, kind: "prepaid" | "free_quota", amount, currency?, usd_rate?, expires_at?, label?}: a balance or free quota on a provider key. |
PATCH /api/admin/v1/lifecycle/credits/{id} |
providers:write |
Change a credit. |
DELETE /api/admin/v1/lifecycle/credits/{id} |
providers:write |
Remove it. |
POST /api/admin/v1/lifecycle/credits/{id}/refresh |
providers:write |
Read the balance from the provider now (DeepSeek, OpenRouter, Moonshot), one call. |
Gears
The org's gears are what GET /v1/gears serves to the venom CLI (Gears from the server).
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/gears |
routing:read |
The gears, the lock, the default, warnings and the models the org serves now. |
PUT /api/admin/v1/gears |
org:manage |
{gears?, locked?, default?} (at least one; any other field is 400). gears replaces the list; locked: true means members can only use these gears; default names a gear or null. Invalid gears: 400 invalid_gears with errors. Dropping a gear a running experiment uses: 409 experiment_running. Audited gears.updated. |
DELETE /api/admin/v1/gears |
org:manage |
Remove the list and the lock. |
Gear experiments
An A/B test of two gears over members' sessions. One running per org.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/experiments |
routing:read |
The org's experiments, newest first, and what the create form offers. |
POST /api/admin/v1/experiments |
org:manage |
Start one (fields below). Audited experiment.created. |
GET /api/admin/v1/experiments/{id} |
routing:read |
Results per arm and the verdict. Another org's id is 404. |
POST /api/admin/v1/experiments/{id}/stop |
org:manage |
Take no more sessions; answers the results. |
POST /api/admin/v1/experiments/{id}/promote |
org:manage |
{arm?: "b"}: that arm's gear becomes the org default and the experiment ends as promoted. |
DELETE /api/admin/v1/experiments/{id} |
org:manage |
Remove an ended experiment and its sessions. |
| Field | Default | Meaning |
|---|---|---|
gear_a, gear_b |
required | two different gears of the org |
name |
<a> vs <b> |
up to 100 characters |
split |
50 | percent of sessions in arm B, 1 to 99 |
audience |
all |
all, members (with members: user ids) or teams (with teams: key group ids) |
duration_days or ends_at |
none | 1 to 90 days, or an end time; not both |
max_sessions |
none | stop after this many sessions |
opt_out |
true | members may opt out of the experiment |
Prompt experiments
The same for a team library prompt: two versions, one running test per prompt.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/prompt-experiments |
routing:read |
Tests, newest first (?item= for one prompt). |
POST /api/admin/v1/prompt-experiments |
org:manage |
{item_id, version_a?, version_b, name?, split?, audience?, members?, teams?, duration_days?, ends_at?, max_sessions?}. version_b: "draft" tests the unpublished draft. |
GET /api/admin/v1/prompt-experiments/{id} |
routing:read |
Results per arm and the verdict. |
POST /api/admin/v1/prompt-experiments/{id}/stop |
org:manage |
New sessions stop joining; results stay. |
POST /api/admin/v1/prompt-experiments/{id}/promote |
org:manage |
{arm?: "b"}: that arm's text is published as a new library version. |
DELETE /api/admin/v1/prompt-experiments/{id} |
org:manage |
Remove an ended test and its sessions. |
Routing policy
An org can order up to five routing modes for the whole org (alias "") or one model alias: private (its
own daemons), trusted (allowlisted public daemons), public (public daemons only), managed (public
daemons plus the cloud's providers) and cloud (the cloud's providers only). Without a policy the default
routing applies. A policy without managed or cloud never leaves your own and public daemons.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/routing |
routing:read |
The GET /v1/routing view over every key of the org: targets are daemons and providers. ?window=24h, &key=<name>, &recent=10. |
GET /api/admin/v1/routing/modes |
routing:read |
The org's policy rows and its trusted-node allowlist. |
PUT /api/admin/v1/routing/modes |
routing:write |
{alias?: "", modes, disabled?, max_price?, prefer?}. modes: 1 to 5 of the above, in order. disabled: modes switched off but kept in place (one stays on). max_price: USD per 1M tokens, 0 to 1,000,000, null for none. prefer: cheapest, fastest, local or cloud. |
DELETE /api/admin/v1/routing/modes |
routing:write |
?alias=… removes that row ("" the org row). |
GET /api/admin/v1/routing/preview |
routing:read |
?model=…[&team=<key group id>]: the candidate order the router gives that model under the policy. |
GET /api/admin/v1/routing/ttft |
routing:read |
Measured time to first token per cloud provider target, what prefer: "fastest" orders by. |
Auto routing (venom-auto)
venom-auto sends each request to a cheap, balanced or premium tier by rules over the role, prompt size,
tools, depth, language and class.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/auto-routing |
routing:read |
The settings with defaults filled in, warnings and the models served now. |
PUT /api/admin/v1/auto-routing |
org:manage |
{tiers?, rules?, default_tier?, main_role?} (at least one). Invalid: 400 invalid_auto_routing with errors. Audited auto_routing.updated. |
DELETE /api/admin/v1/auto-routing |
org:manage |
Back to the defaults. |
GET /api/admin/v1/auto-routing/savings |
usage:read |
?days=7|30: requests by tier, spend against an all-premium counterfactual, error and retry rates. |
GET /api/admin/v1/auto-routing/languages |
usage:read |
?days=30|90: the best model per programming language, from how sessions ended. |
POST /api/admin/v1/auto-routing/test |
routing:read |
{prompt, role?, lang?, tools?, has_image?, depth?, prompt_tokens?, settings?}: the tier and model it would pick, and why. Nothing is sent to a model. |
Defaults: tiers cheap: [venom-fast], balanced: [venom-default], premium: [venom-smart]; default tier
balanced; main_role: false; up to 32 rules and 8 models per tier. The default rules send workers,
classifier, summary and reflex roles and short tool-less chat to cheap, and the smart role and multi-step
reasoning to premium.
Shadow routing
Mirror a share of matching requests to a candidate model and compare the answers, without the client seeing them.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/shadow |
routing:read |
Settings, tests with figures and verdicts, latest samples. |
PUT /api/admin/v1/shadow |
org:manage |
{enabled?, judge_model?}. |
Tests live under /api/admin/v1/shadow/tests: POST starts one (org:manage) with
{candidate, sample_pct, daily_cap_usd, match_model?, match_gear?, match_role?, max_concurrency?: 2, name?}
(at least one match; sample_pct above 0 and at most 100; daily_cap_usd above 0 and at most 1,000;
concurrency 1 to 8; up to 20 tests). GET, PATCH ({name?, sample_pct?, daily_cap_usd?, max_concurrency?, status?})
and DELETE /api/admin/v1/shadow/tests/{id}; POST /api/admin/v1/shadow/tests/{id}/switch moves the matching
gear roles to the candidate (the old model kept behind it) and stops the test; POST /api/admin/v1/shadow/tests/{id}/revert
undoes a switch while the gear roles still read what it wrote. Both need org:manage and are audited.
Guardrails
Org and key group (or resold customer) guardrails, with stable codes such as GR-ORG-PII-001. The rule shapes, the
catalog and how they reach the client are in Guardrails. A member's own rules are
under Your own guardrails.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/guardrails |
audit:read |
Every layer as you may see it, the catalog, and 7-day counts. |
POST /api/admin/v1/guardrails |
org:manage (team layer: or that key group's admin) |
{layer: "org" | "team", owner?, catalog? | rule}; owner is the key group id or customer:<id>. Up to 200 per layer. Answers the rule with its code. |
GET /api/admin/v1/guardrails/{code} |
org:read |
One code's page as you may see it. |
PATCH /api/admin/v1/guardrails/{code} |
as for adding it | Change a stored rule. |
DELETE /api/admin/v1/guardrails/{code} |
as for adding it | Remove it. |
GET /api/admin/v1/guardrails/effective |
audit:read |
?team=&customer=&member=: the resolved set in the order it runs. A member's own rules are counted, never shown. |
PUT /api/admin/v1/guardrails/overrides |
the key group's admin or org:manage |
{owner, code, enabled?, action?, mode?, clear?}: a key group's override of an org rule, as far as its lock allows. |
POST /api/admin/v1/guardrails/draft |
org:manage or the key group's admin |
{text, layer?, gear?}: the classifier model drafts a rule; nothing is saved. Needs guardrail drafting on. |
POST /api/admin/v1/guardrails/suggestions/{id} |
the key group's admin or org:manage |
{approve}: add a member's suggested rule to the key group, or decline it. |
POST /api/admin/v1/guardrails/test (audit:read) runs
{text, model?, direction?, team?, customer?, member?, draft?} through the effective set; nothing is stored.
Prompt filters
Rules run on prompts (and, with direction, on answers) before a request is sent: redact, block, warn or log.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/prompt-filters |
audit:read |
The filters, the detectors and presets, and the last 24 hours of hits. |
PUT /api/admin/v1/prompt-filters |
org:manage |
{enabled: true, apply_to, rules, classifier?} replaces them. A rule is {id, name, enabled, action: "redact" | "block" | "warn" | "log", direction?, match, scope?}; the classifier is {enabled, model, mode, timeout_ms, on_error, categories, responses}. Audited prompt_filters.updated. |
POST /api/admin/v1/prompt-filters/test (audit:read) dry-runs the filters (or a draft) on pasted text; the
text is never stored. A blocked request gets 403 prompt_blocked, and a classifier that fails closed
503 prompt_classifier_unavailable (Errors).
Errors
| Status | code |
When |
|---|---|---|
| 400 | invalid_request, invalid_gears, invalid_auto_routing |
a bad field; the last two carry errors |
| 403 | forbidden |
the role lacks the permission, or the route is the operator's |
| 404 | not_found |
an unknown id or another org's |
| 409 | conflict, experiment_running |
a revoked key, a rotation already open, a gear in a running experiment |
| 503 | vault_not_configured |
provider keys need VENOM_VAULT_KEYS |
Related
- Admin API: orgs, members and keys
- Venom Cloud APIs overview:
x-venom-profile,x-venom-auto-*and the other routing headers - Gears, Guardrails
- Orchestrator routing: the same ideas on a self-hosted orchestrator