Admin API: knowledge, tools and integrations
Manage an org's library, memory, marketplace, starter packs, evals, red-team runs, Slack, Linear and Jira integrations and the knowledge Ask box over /api/admin/v1.
These routes manage what an org gives its agents and members: shared prompts and skills, agreed facts, an
internal plugin catalog, starter packs, eval runs, red-team checks, and the Slack, Linear and Jira apps the org
connects. The venom CLI reads the published side of most of them over /v1 with a client key; this page is the
admin side.
Credentials, roles and the error shape are on Venom Cloud APIs overview.
Most routes read with routing:read and change with org:manage; each table says when it differs. The operator
names the org with ?tenant= on reads and tenant_id in bodies.
export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_ADMIN_KEY"
# publish a prompt the whole org gets as /org:review
curl -s "$VENOM_CLOUD/api/admin/v1/library" -H "$ADMIN" -H "Content-Type: application/json" -d '{
"kind": "prompt", "name": "review", "publish": true, "note": "first version",
"content": {"description": "Review the staged diff", "body": "Review the staged changes. Focus on $ARGUMENTS"}
}'
# add an approved fact to org memory, for one repository
curl -s "$VENOM_CLOUD/api/admin/v1/memory" -H "$ADMIN" -H "Content-Type: application/json" \
-d '{"text": "We use pnpm, never npm.", "repo": "acme/web"}'Team library
Prompts (slash-command templates, /org:<name> in the CLI) and skills (a SKILL.md plus text files). Members
get the published version whose scope takes their key's key group (team); drafts are never served.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/library |
routing:read |
The org's items with usage over 30 days. |
POST /api/admin/v1/library |
org:manage |
{kind: "prompt" | "skill", name, content, required?, team_ids?, publish?, note?, tenant_id?}. Without publish: true the content is a draft. |
GET /api/admin/v1/library/{id} |
routing:read |
The item: draft, published content, versions, usage per day. |
PATCH /api/admin/v1/library/{id} |
org:manage |
{draft?, required?, team_ids?}: save or drop the draft (draft: null), set the scope (team_ids: null is the whole org). |
DELETE /api/admin/v1/library/{id} |
org:manage |
Remove the item and its versions. |
GET /api/admin/v1/library/{id}/versions/{version} |
routing:read |
One version's content, for a diff. |
POST /api/admin/v1/library/{id}/publish |
org:manage |
{note?}: the draft becomes the next version. |
POST /api/admin/v1/library/{id}/rollback |
org:manage |
{version, note?}: that version's content is published as the next version (numbers only grow). |
POST /api/admin/v1/library/{id}/test |
org:manage |
"Test this change": queue the org's golden tasks with one version as A and another (default the draft) as B to an eval runner. |
content (and draft) is {description, tags?, body, argument_hint?, params?} for a prompt and
{description, tags?, body, files?} for a skill (files: [{path, content}]). 409 library_item_exists, 409 library_full.
Names follow the Agent Skills rule (^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$). required: true makes the CLI always
load the item. Limits: 200 items per org; a description up to 1,024 characters and up to 10 tags; a prompt body up
to 32 KiB with up to 20 parameters; a skill body up to 64 KiB with up to 20 files of 64 KiB (256 KiB in all).
Prompt A/B tests on live sessions are the prompt-experiments routes, on the routing page of the admin API.
Org memory
Facts a team agrees on, loaded into each venom session's prompt. Members propose; org:manage approves.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/memory |
routing:read |
Every fact: approved, pending and rejected. |
POST /api/admin/v1/memory |
routing:read |
{text, team_ids?, repo?, owner?, status?, tenant_id?}. Approved at once for org:manage (unless status: "pending"), else a pending proposal. |
GET /api/admin/v1/memory/{id} |
routing:read |
One fact. |
PATCH /api/admin/v1/memory/{id} |
org:manage |
{text?, team_ids?, repo?, owner?}. |
DELETE /api/admin/v1/memory/{id} |
org:manage |
Remove it. |
POST /api/admin/v1/memory/{id}/approve |
org:manage |
{note?}: a pending or rejected fact goes live. |
POST /api/admin/v1/memory/{id}/reject |
org:manage |
{note?}: a pending or approved fact stops being served. |
POST /api/admin/v1/memory/{id}/confirm |
org:manage |
"Still true": sets confirmed_at to now. The console flags facts not confirmed for 90 days. |
repo is a repository pattern matched against the checkout's origin (* within a segment, ** across
segments; acme/web matches any host). A fact is up to 500 characters, an owner up to 120, a pattern up to 200.
The same words already approved or waiting are 409 memory_exists (with its id). At most 100 approved facts per org (409 memory_full) and 200 waiting (409 memory_queue_full). Text that matches
a secret pattern is 422 secrets_found.
Knowledge Ask
POST /api/admin/v1/knowledge/ask (routing:read) answers a question from the org's own sources with citations:
approved memory facts, published library items, and session summaries when the org collects them and the caller
holds logs:read.
curl -s "$VENOM_CLOUD/api/admin/v1/knowledge/ask" -H "$ADMIN" -H "Content-Type: application/json" \
-d '{"question": "How do we deploy the web app?", "gear": "default"}'Body: {question, gear?, tenant_id?}. The model is the gear's summary role (else its main model), at most 700
output tokens, through the normal inference path, paid by an internal key of the caller. A question nothing
matches is answered without a model call. venom ask in the CLI uses the same sources plus the repository's docs.
Org marketplace
An org's catalog of plugins, skills and MCP server packages. Members browse, review and submit; org:manage
approves each version before anyone can install it (venom plugin install org:<name>).
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/marketplace |
routing:read |
The catalog: listings with versions and state, venom's featured plugins, library skills and approved MCP servers. |
POST /api/admin/v1/marketplace |
routing:read |
Submit a listing or a new version; pending until approved. Body below. |
GET /api/admin/v1/marketplace/{id} |
routing:read |
A listing with its versions, reviews and installs. |
PATCH /api/admin/v1/marketplace/{id} |
org:manage |
{title?, description?, homepage?, kind?, deprecated?, pinned_version?}. |
DELETE /api/admin/v1/marketplace/{id} |
org:manage |
Remove the listing. |
POST /api/admin/v1/marketplace/{id}/versions/{version}/approve |
org:manage |
{reason?}. |
POST /api/admin/v1/marketplace/{id}/versions/{version}/reject |
org:manage |
{reason?}. |
GET /api/admin/v1/marketplace/{id}/versions/{version}/bundle |
org:manage, or the submitter |
The uploaded .tgz, for review. |
GET /api/admin/v1/marketplace/featured/{name} |
routing:read |
One of venom's own first-party plugins or skills, with the org's reviews of it. |
PUT /api/admin/v1/marketplace/reviews |
routing:read |
{ref, rating, body?}: the caller's review. ref is listing:<name>, featured:<name>, skill:<name> or mcp:<key>; rating 1 to 5; body up to 1,000 characters. |
DELETE /api/admin/v1/marketplace/reviews |
the author, or org:manage for anyone's |
{ref, author?}. |
A submission is {name?, kind?: "plugin" | "skill" | "mcp", title?, description?, homepage?, version?, note?, source, bundle_b64?, permissions?, tenant_id?}. source is {type: "bundle"} with bundle_b64 (a npm pack
.tgz, at most 2 MiB, 16 MiB unpacked, 1,000 files), {type: "npm", package, version, integrity} or
{type: "git", url, commit} (a full 40-hex commit). For a bundle the cloud reads the name and the permissions it
asks for (code, tools, network, env, commands); for npm and git the submitter declares them and the CLI
checks them at install. A bad bundle is 422 with bundle_corrupt, bundle_link, bundle_path,
bundle_duplicate, bundle_too_large, bundle_empty, bundle_not_a_plugin, bundle_manifest or
bundle_dependencies. Limits: 200 listings per org, 50 versions per listing.
MCP catalog
GET /api/admin/v1/mcp/catalog returns the curated MCP servers the console offers when an admin adds one to a
key group's policy. It is static data shipped with the cloud: any authenticated admin caller may read it, and nothing
is fetched from a registry.
Starter packs
A starter pack sets an org up for one line of work in one step: gears, prompt and response filter rules, library
items, a gear budget, permission rules and memory facts. The packs are legal, accounting and clinics.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/starter-packs |
routing:read |
The packs, each one's install state in this org, the models its gears can use, the defaults. |
GET /api/admin/v1/starter-packs/{id} |
routing:read |
The pack in full, the plan with the default choices and, when installed, the uninstall plan. |
POST /api/admin/v1/starter-packs/{id} |
org:manage (budgets also billing:manage or org:manage) |
{local_model, strong_model, names, budget_usd, dry_run?}. With dry_run: true the answer is the plan (steps: kind, name, create or skip with why; warnings); otherwise it installs. |
DELETE /api/admin/v1/starter-packs/{id} |
org:manage |
Uninstall what the install created and is still there; ?dry_run=1 returns the plan. |
strong_model is optional and off by default: without it every gear runs on the org's daemons. An install never
changes what exists (a same-named gear, rule, item or fact is skipped). A second install is 409 pack_installed.
Each resource's own operation writes its audit row, plus starter_pack.installed or starter_pack.uninstalled.
Evals
Eval runs are queued here and run on a machine the org controls (venom eval run --cloud); the cloud never runs a
trial. Read with routing:read; queue, cancel and manage golden tasks and runners with org:manage.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/evals |
routing:read |
Runners, golden tasks, run history, gears, models and prices, the built-in task catalog, open suggestions. |
POST /api/admin/v1/evals/runs |
org:manage |
Queue a run (body below). |
GET /api/admin/v1/evals/runs/{id} |
routing:read |
A run with its results and the comparison of each variant with A. |
POST /api/admin/v1/evals/runs/{id}/cancel |
org:manage |
Cancel a queued or running run; its key is revoked now. |
DELETE /api/admin/v1/evals/runners/{id} |
org:manage |
Remove a runner; its queued and running runs are cancelled. |
POST /api/admin/v1/evals/golden |
org:manage |
Save a golden task (body below). |
PUT /api/admin/v1/evals/golden/{id} |
org:manage |
Replace one. |
DELETE /api/admin/v1/evals/golden/{id} |
org:manage |
Delete one. |
POST /api/admin/v1/evals/golden/draft |
the share's viewers | {session_share_id}: a golden task drafted from a shared session (its first prompt, the last test command, the repository folder). Saves nothing. |
POST /api/admin/v1/evals/suggestions/{id}/dismiss |
org:manage |
Drop a "run golden tasks?" suggestion opened by a gear change. |
A run is {runner_id, variants, tasks, k, max_usd, trigger?, suggestion_id?, tenant_id?}:
| Field | Meaning |
|---|---|
variants |
up to four (A to D), each {label, gear} (the gear's current settings are snapshotted) or a full variant |
tasks |
{kind: "builtin", categories: [...]} or {kind: "golden", ids: [...]} |
k |
trials per task and variant, 1 to 10 |
max_usd |
the spend cap, at most $1,000 and at most the runner's own cap |
The run's trials use a key minted for it, with a hard budget equal to the cap and a 12-hour expiry. A golden task
is {name, prompt, repo, ref, setup?, check, timeout_sec?, session_share_id?, tenant_id?}: the repository (a git
URL without credentials, or a name the runner knows), the commit before the work, setup commands, the prompt, and
a check command whose exit 0 means done. 200 golden tasks per org, names unique.
Red team
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/redteam |
audit:read |
The attack corpus, the org's runs (the trend) and the latest run's results. |
POST /api/admin/v1/redteam/runs |
org:manage |
{dry_run?}: run the corpus's free cases (guardrail and model-list cases) against the org's guardrails and keep the run. Audited redteam.run. Nothing is sent to a model. |
GET /api/admin/v1/redteam/runs/{id} |
audit:read |
One run with every case's result and evidence. |
The paid model cases run from the CLI with venom redteam run --max-usd.
Integrations
An org connects its own Slack app, Linear workspace or Jira Cloud site. Nothing is registered on any account and
no call goes out until an admin saves credentials. Secrets are sealed in the vault (503 vault_not_configured
without one) and shown only as their last four characters.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/integrations |
org:read |
Every kind offered (slack, linear, jira), connected or not, with hints and the URLs to paste into the other app. |
POST /api/admin/v1/integrations |
org:manage |
{kind, tenant_id?}: the org's row, pending until its credentials are saved. |
GET /api/admin/v1/integrations/{id} |
org:read |
The row; for Slack also the app manifest, channels, linked members, the latest 50 answers and 30-day totals. |
PATCH /api/admin/v1/integrations/{id} |
org:manage |
{secrets?, config?, status?, team_id?}. New credentials are checked against the org's own app before they are sealed (400 slack_rejected with Slack's reason). status moves between active and paused; team_id is the key group whose keys book its requests (the API keeps the name team). |
DELETE /api/admin/v1/integrations/{id} |
org:manage |
Disconnect; its keys are revoked. |
POST /api/admin/v1/integrations/{id}/check |
org:read |
Whether the saved Slack bot token still works (one auth.test call). |
PUT /api/admin/v1/integrations/{id}/channels |
org:manage |
{channel_id, channel_name?, gear}: the gear a Slack channel answers with. |
DELETE /api/admin/v1/integrations/{id}/channels |
org:manage |
?channel_id=: the channel goes back to the default gear. |
DELETE /api/admin/v1/integrations/{id}/members/{slack} |
org:manage, or the member |
Unlink a Slack user from its member; its key is revoked. |
GET /api/admin/v1/integrations/slack/link |
a signed-in member | ?code=: what a /venom link code would link. |
POST /api/admin/v1/integrations/slack/link |
a signed-in member | {code}: link the member's Slack user, so answers use their own key, budget and model access. |
Settings per kind:
| Kind | secrets |
config |
|---|---|---|
slack |
signing_secret, bot_token |
default_gear, channels (any or listed), allow_dms, require_link, max_tokens (default 2,000), app_name |
linear |
api_key, webhook_secret |
trigger_label (default venom), repo, repos, base_ref, gear, max_usd_per_job (default 2, at most 100), states, comment_on_start (default on) |
jira |
api_token, webhook_secret (and the site, <name>.atlassian.net) |
as Linear |
Requests an integration makes go through the normal inference path with an internal key of its key group, so routing,
filters, budgets and model access apply, and they are booked with source:slack (or the intake job's key).
Inbound requests from Slack, Linear and Jira land on /api/integrations/* and are checked by their signatures.
Issue intake
Linear or Jira issues handed to venom become jobs for a runner the org controls (venom intake run), which opens a
pull request and reports back.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/intake |
logs:read |
The org's intake jobs (status, cost, pull request), its runners, and which trackers are connected. status filters jobs. |
POST /api/admin/v1/intake/jobs/{id}/cancel |
org:manage |
Stop a job; its key is revoked at once. |
POST /api/admin/v1/intake/jobs/{id}/retry |
org:manage |
Fetch an ended job's issue again from the tracker and queue it again. |
DELETE /api/admin/v1/intake/runners/{id} |
org:manage |
Remove a runner; its running jobs fail, queued ones wait for another runner. |
Provenance registry
The public mesh's model registry: which weights, tokenizer, chat template, quantization and engines a public
daemon must run for a registry id (for example qwen3-8b-awq@1). Every route needs the cloud admin token
(403 forbidden otherwise); org members and key group admin keys cannot use it.
| Route | What it does |
|---|---|
GET /api/admin/v1/registry |
Every entry. |
POST /api/admin/v1/registry |
Create one: {id, model, source, weights_sha256, tokenizer_sha256, template_sha256, quant, engines, tau_milli?, max_mismatch_permille?, cusum_k_milli?, cusum_h_milli?, golden?}. 409 conflict when the id exists. |
GET /api/admin/v1/registry/{id} |
One entry. |
PATCH /api/admin/v1/registry/{id} |
Change fields (400 with nothing to change). |
DELETE /api/admin/v1/registry/{id} |
Delete it. |
Defaults: tau_milli 1000, max_mismatch_permille 5, cusum_k_milli 4, cusum_h_milli 10,000. golden holds
at most 8 preflight cases (256 KiB in all) or null. engines admits vLLM, SGLang and llama.cpp
({"vllm>=0.11"}). Changes are audited registry.create, registry.update.
Errors
The admin error shape and the common codes are on Venom Cloud APIs overview. Codes
specific to these routes are listed in each section: 409 memory_full, 409 memory_queue_full,
422 secrets_found, 422 bundle_*, 409 pack_installed, 400 slack_rejected, 503 vault_not_configured,
503 policy_signing_not_configured (marketplace manifests need a policy-signing key).
Related
- Venom Cloud APIs overview.
- Admin API: logs, audit and alerts: shared sessions, which golden tasks are drafted from.
- Plugins: what a marketplace listing installs.