---
title: "Admin API: providers, gears and routing"
description: 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.
section: cloud
order: 310
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/admin/v1, services/nodejs-cloud/lib/providers/credentials.ts, services/nodejs-cloud/lib/providers/rotation.ts, services/nodejs-cloud/lib/gears/index.ts, services/nodejs-cloud/lib/routing-modes/index.ts, services/nodejs-cloud/lib/auto/tiers.ts, services/nodejs-cloud/lib/pricing/org.ts, services/nodejs-cloud/lib/catalog-sync/index.ts, services/nodejs-cloud/lib/lifecycle, services/nodejs-cloud/lib/experiments/validate.ts, services/nodejs-cloud/lib/prompt-experiments, services/nodejs-cloud/lib/shadow/model.ts, services/nodejs-cloud/lib/guardrails/admin.ts, services/nodejs-cloud/lib/filters/validate.ts, docs/cloud-mesh.md]
features: [cloud.api-admin-gears, cloud.api-admin-providers, cloud.api-admin-routing, cloud.api-admin-auto-routing, cloud.api-admin-pricing, cloud.api-admin-pricing-simulator, cloud.api-admin-catalog-sync, cloud.api-admin-lifecycle, cloud.api-admin-experiments, cloud.api-admin-prompt-experiments, cloud.api-admin-shadow, cloud.api-admin-guardrails, cloud.api-admin-prompt-filters]
---

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](/docs/cloud/api-admin-access.md#calling).

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 {#example}

Add an OpenAI key to the org, check it lists models, then make the org serve from cloud providers first:

```bash
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"
```

```python
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 {#providers}

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](/docs/cloud/api-admin-access.md#settings)).

### Catalog sync {#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 {#pricing}

| 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](/docs/cloud/api-admin-access.md#settings)). |

### Pricing simulator {#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 {#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 {#gears}

The org's gears are what `GET /v1/gears` serves to the venom CLI ([Gears from the server](/docs/configuration/gears.md#server-gears)).

| 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 {#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 {#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 {#routing}

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) {#auto-routing}

`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 {#shadow}

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 {#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](/docs/security/guardrails.md). A member's own rules are
under [Your own guardrails](/docs/cloud/api-admin-access.md#me).

| 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 {#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](/docs/cloud/api-overview.md#errors)).

## 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 {#related}

- [Admin API: orgs, members and keys](/docs/cloud/api-admin-access.md)
- [Venom Cloud APIs overview](/docs/cloud/api-overview.md#headers): `x-venom-profile`, `x-venom-auto-*` and the other routing headers
- [Gears](/docs/configuration/gears.md), [Guardrails](/docs/security/guardrails.md)
- [Orchestrator routing](/docs/orchestrator/routing.md): the same ideas on a self-hosted orchestrator
