Skip to content
Docs menu

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.

View .md

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