Knowledge and tools API
Read the org's memory, library and plugin marketplace with a client key, ask questions over them, and run eval, issue-intake and red-team jobs on machines you control.
An org keeps shared knowledge in Venom Cloud: approved facts (memory), prompts and skills (the library), and a catalog of approved plugins (the marketplace). Admins curate them in the console; these client-key routes are how an agent reads them. The venom CLI fetches them at session start and caches them on disk, so it keeps working offline. The same section has the runner protocols: machines you control claim eval runs and tracker issues from the cloud, do the work, and report back. The cloud never runs an agent itself.
Every route takes a client key (Authorization: Bearer vck_…) and answers with cache-control: no-store; errors
use the shape in Venom Cloud APIs overview.
Routes
| Route | What it does |
|---|---|
GET /v1/memory |
the org's approved facts in the scope of the key's key group (ETag, 304) |
POST /v1/memory/proposals |
propose a fact; pending until an admin approves it |
POST /v1/knowledge/ask |
answer a question from the org's memory, library and session summaries, with sources |
GET /v1/library |
the org's published prompts and skills in the scope of the key's key group (ETag, 304) |
POST /v1/library/usage |
report how often library items ran (counts only) |
POST /v1/library/experiments/{id}/sessions |
record which arm of a prompt A/B test a session is in |
GET /v1/marketplace |
the org's approved plugins, skills and MCP packages (ETag, 304) |
GET /v1/marketplace/{name} |
the signed install manifest of one listing |
GET /v1/marketplace/{name}/bundle |
an approved version's uploaded .tgz |
POST /v1/marketplace/installs |
report an install or removal (the org's install count) |
POST /v1/evals/runners |
an eval runner's hello and heartbeat |
POST /v1/evals/runners/{id}/claim |
take the oldest eval run queued to this runner (204 when none) |
POST /v1/evals/jobs/{id}/progress |
trials done; renews the lease; answers whether to stop |
POST /v1/evals/jobs/{id}/result |
the run's results; the cloud computes the comparison |
POST /v1/intake/runners |
an intake runner's hello and heartbeat |
POST /v1/intake/runners/{id}/claim |
take the oldest queued tracker issue for a repository this runner has (204 when none) |
POST /v1/intake/jobs/{id}/progress |
the job's phase; renews the lease; answers whether to stop |
POST /v1/intake/jobs/{id}/result |
the job's end: a pull request, no changes, or a failure |
POST /v1/redteam/runs |
run the red-team corpus's free cases on the key's guardrails and keep the run |
The generated reference for these routes is at /docs/api/cloud.
Cached reads: memory, library, marketplace
GET /v1/memory, GET /v1/library and GET /v1/marketplace answer with an ETag ("mem-<32 hex>",
"lib-<32 hex>", "mkt-<32 hex>", a hash of the body). Send it back as If-None-Match and an unchanged answer is
304 with no body. Poll these freely; cache the body on disk and use it when the cloud is unreachable.
import { readFile, writeFile } from "node:fs/promises";
async function library(cachePath: string) {
const cached = await readFile(cachePath, "utf8").then(JSON.parse).catch(() => null);
const r = await fetch("https://cloud.usevenom.dev/v1/library", {
headers: { Authorization: `Bearer ${process.env.VENOM_KEY}`, ...(cached ? { "If-None-Match": cached.etag } : {}) },
});
if (r.status === 304) return cached.body;
const body = await r.json();
await writeFile(cachePath, JSON.stringify({ etag: r.headers.get("etag"), body }));
return body;
}Org memory
Facts a team agrees on ("we use pnpm", "never touch billing/ without review"). venom puts the ones that apply to the session's repository into one system-prompt section at session start; it never changes mid-session.
curl -s "$VENOM_CLOUD/v1/memory" -H "Authorization: Bearer $VENOM_KEY"{"object": "venom.memory", "source": "Acme Corp", "items": [
{"id": "0193…", "text": "Use pnpm, never npm.", "scope": "org", "owner": "platform", "confirmed_at": "2026-10-01T08:00:00Z", "updated_at": "2026-10-01T08:00:00Z"},
{"id": "0193…", "text": "Deploys go out on Fridays.", "scope": "repo", "repo": "acme/web", "owner": "web", "confirmed_at": null, "updated_at": "2026-10-20T12:00:00Z"}
]}itemsare the approved facts whose key groups include the key's key group, in the order they were approved. Pending and rejected facts are never served.scopeisrepowhen the fact has a repository pattern, elseteamororg.repois a pattern matched by the client against its normalizedoriginremote (github.com/acme/web):*matches within one path segment,**across segments. A pattern whose first segment has no dot matches after any host (acme/webmatchesgithub.com/acme/webandgitlab.example.com/acme/web). The cloud does not know your repository; the client filters.
POST /v1/memory/proposals (at most 16 KiB):
| Field | Type | Default | Notes |
|---|---|---|---|
text |
string | required | 1 to 500 characters of plain text |
scope |
org | team | repo |
org (repo when repo is given) |
team is the key's key group; repo needs repo |
repo |
string | a repository pattern, at most 200 characters | |
reason |
asked | corrections |
why venom proposed it | |
session_id |
string | the session it came from |
A new proposal answers 201 {object: "venom.memory.proposal", id, status: "pending", duplicate: false}. The same
words (case, punctuation and a leading "remember that" ignored) already approved or waiting in the same scope
answer 200 with that fact's id, its status and duplicate: true. Refusals: 422 secrets_found,
429 too_many_proposals (20 a day per key), 409 memory_queue_full (200 waiting), 400 invalid_request (a bad field; the message names it).
Knowledge Q&A
POST /v1/knowledge/ask answers a question from the sources the key may read: the org's memory and library in the
scope of the key's key group, and session summaries when the org collects them and the key belongs to a member whose role holds
logs:read. It is what venom ask calls. Answers cite sources as [S1].
import os, requests
r = requests.post("https://cloud.usevenom.dev/v1/knowledge/ask",
headers={"Authorization": f"Bearer {os.environ['VENOM_KEY']}"},
json={"question": "How do we cut a release?", "gear": "quick"}, timeout=130)
a = r.json()
print(a["answer"])
for s in a["sources"]:
print(s["id"], s["kind"], s["title"], "cited" if s["cited"] else "")| Field | Type | Default | Notes |
|---|---|---|---|
question |
string | required | at most 600 characters |
gear |
string | the org's default gear | the gear's summary role answers (its main model when it has none) |
local |
array | [] |
passages from your own checkout, at most 6 used: {path, heading?, text, tour?}; text is clipped to 1,400 characters, path at most 300 |
The answer is {object: "venom.knowledge.answer", question, answer, sources: [{id, kind, title, meta, link, cited}], mode, searched: {memory, library, summaries, local}, gear, model, usage}. searched.summaries is a count, "off"
or "no access"; link is a console path, null for a local passage. At most 8 passages (9,000 characters in all)
go to the model, with at most 700 output tokens, through the normal inference path: the org's routing, filters,
budgets and the key's model access apply, and the key pays. A question nothing matches is answered without a model
call. Errors: 400 invalid_request (no question, too long, bad local), 404 gear_not_found, 409 no_gear,
502 empty_answer. The route may take up to 120 seconds.
Team library
Prompts (slash-command templates, /org:<name> in venom) and skills (a SKILL.md and files beside it). See
Team library for how venom uses them.
{"object": "venom.library", "source": "Acme Corp", "items": [
{"kind": "prompt", "name": "release-notes", "version": 3, "required": false, "description": "Draft release notes",
"tags": ["release"], "body": "Write release notes for $ARGUMENTS", "argument_hint": "<tag>", "params": [],
"sha256": "9f2c…", "updated_at": "2026-10-30T10:00:00Z"},
{"kind": "skill", "name": "db-migrations", "version": 1, "required": true, "description": "How we write migrations",
"tags": [], "body": "…", "files": [{"path": "checklist.md", "content": "…"}], "sha256": "41aa…", "updated_at": "2026-10-12T09:00:00Z"}
]}- Only each item's published version in the scope of the key's key group is served; drafts never are.
sha256is the SHA-256 of the version's content as canonical JSON.required: trueasks the client to always load the item. - A prompt under a running A/B test carries
experiment(id,name,split,ends_atand both arms'body,argument_hint,params,version,sha256) for keys in the test's audience. The client puts a session in armbwhen the first 4 bytes ofsha256("<id>:<session id>"), as a big-endian integer mod 10000, are belowsplit× 100, elsea.
| Route | Body | Answer |
|---|---|---|
POST /v1/library/usage |
{counts: [{kind, name, count}]}: at most 200 entries, count 1 to 10,000 (at most 64 KiB) |
{accepted: <n>}; names the key's key group can't see are ignored |
POST /v1/library/experiments/{id}/sessions |
{session_id, arm: "a" | "b"} (at most 4 KiB), once per session when it first runs the prompt under test |
{object: "venom.prompt_experiment_session", experiment_id, session_id, arm, recorded}; recorded: false (not an error) for an ended test, a key outside the audience or an internal key; 400 arm_mismatch when arm is not the hash's |
Usage reports carry counts only, never arguments or text.
Org marketplace
The org's catalog of approved plugins (venom, pi and Claude Code plugins), skills and MCP server packages.
venom plugin install org:<name>[@<version>] installs from it (see Installing plugins).
curl -s "$VENOM_CLOUD/v1/marketplace" -H "Authorization: Bearer $VENOM_KEY"
curl -s "$VENOM_CLOUD/v1/marketplace/venom-lint?version=1.2.0" -H "Authorization: Bearer $VENOM_KEY"
curl -s -o venom-lint.tgz "$VENOM_CLOUD/v1/marketplace/venom-lint/bundle?version=1.2.0" -H "Authorization: Bearer $VENOM_KEY"GET /v1/marketplace answers {object: "venom.marketplace", source, items}. Each item: name, kind (plugin,
skill, mcp), title, description, homepage?, version (what org:<name> installs: the pinned version,
else the newest approved), versions (every approved version, newest first), pinned, deprecated?: {reason},
format (venom, pi, claude, skill, unknown), source_type (bundle, npm, git), permissions
(code, tools, network, env, commands), installs, rating: {average, count}, updated_at. Every key group of
the org sees the same catalog; a listing with no approved version is not listed.
GET /v1/marketplace/{name}[?version=] answers the manifest an installer must verify before fetching code:
{"format": "venom.marketplace/v1", "kid": "k1", "issued_at": "2026-11-03T09:00:00Z", "expires_at": "2026-11-03T09:15:00Z",
"tenant_id": "…", "source": "Acme Corp",
"listing": {"name": "venom-lint", "kind": "plugin", "title": "Lint", "description": "…", "version": "1.2.0", "format": "venom",
"source": {"type": "bundle", "sha256": "<64 hex>", "bytes": 18234},
"permissions": {"code": true, "tools": ["lint_run"], "network": [], "env": [], "commands": []},
"pinned": false, "approved_by": "…", "approved_at": "…"},
"sig": "…"}sigis Ed25519 over the canonical JSON withoutsig, with the key that signs the org's policy (the onevenom cloud loginpinned). Check it,expires_at(15 minutes after issue),tenant_idandnamebefore you use the listing. No signing key:503 policy_signing_not_configured.sourceis{type: "bundle", sha256, bytes},{type: "npm", package, version, integrity}(SHA-512) or{type: "git", url, commit}(a full 40-hex commit). The cloud never fetches npm or git; the installer does and checks the integrity or commit.- Without
?version, the pinned version, else the newest approved. A pinned listing serves only its pin (409 version_pinned,error.pinned); an unknown or unapproved version is404 version_not_found.
GET /v1/marketplace/{name}/bundle?version= returns the uploaded .tgz (application/gzip, at most 2 MiB)
with x-venom-sha256. Check the SHA-256 against the signed manifest's source.sha256, not against the header.
404 no_bundle for a listing whose source is npm or git.
POST /v1/marketplace/installs {name, version, event: "installed" | "removed"} (at most 4 KiB) answers
{accepted: true, installs: <n>}. The count is per client key. Names the org doesn't have answer accepted: false.
Runner protocol: evals and issue intake
Evals and issue intake share one protocol. A runner is a machine you control, with a client key (venom cloud login, or any shared key without a purpose). It only dials out:
- Hello.
POST /v1/{evals|intake}/runnersregisters one runner per (key group, name) and is repeated between polls as the heartbeat; the console shows it online for 2 minutes after. Answer:{object: "eval_runner" | "intake_runner", id, name, poll_ms: 5000, max_usd}.410 runner_removedwhen an admin removed that name. - Claim.
POST /v1/{evals|intake}/runners/{id}/claim(no body) hands over the oldest queued job, or204. The job carriesbase_url(the cloud's/v1) and a new client key minted for the job: hard daily and monthly budgets equal to the job's cap, an expiry at the job's deadline, and apurposeso its spend is booked apart. Use that key, never your own, for the job's model calls. - Progress.
POST /v1/{evals|intake}/jobs/{id}/progressat least every 15 seconds renews a 3-minute lease and answers{stop, reason?, spent_usd, cap_usd}. Stop whenstopistrue:reasoniscancelled,capped(the key's bookings reached the cap) orlost(the lease ran out). - Result.
POST /v1/{evals|intake}/jobs/{id}/resultends the job and revokes its key.
A running job with no progress for 3 minutes fails at the next read, claim or sweep, and its key is revoked; a
queued job no runner claims in 7 days fails. 404 not_found for a runner or job of another key group.
import os, time, requests
base = "https://cloud.usevenom.dev/v1"
me = {"Authorization": f"Bearer {os.environ['VENOM_KEY']}"}
runner = requests.post(f"{base}/intake/runners", headers=me,
json={"name": "build-box-1", "kind": "cli", "max_usd": 5, "repos": ["acme/web"]}).json()
while True:
r = requests.post(f"{base}/intake/runners/{runner['id']}/claim", headers=me)
if r.status_code == 204:
time.sleep(runner["poll_ms"] / 1000)
requests.post(f"{base}/intake/runners", headers=me, json={"name": "build-box-1", "kind": "cli", "repos": ["acme/web"]})
continue
job = r.json() # job["key"] is the job's own vck_ key, job["base_url"] its /v1
# ... work in a worktree, POST progress every <=15 s, stop when the answer says so ...
requests.post(f"{base}/intake/jobs/{job['id']}/result", headers=me,
json={"status": "done", "pr_url": "https://github.com/acme/web/pull/42", "summary": "Fixed the retry flake"})Evals
venom eval run --cloud is the reference runner. The console queues runs (up to four gear variants A to D, a task
set, k, a cap); the runner runs the eval suite and reports.
| Message | Fields |
|---|---|
| hello body | name (required, ^[A-Za-z0-9][A-Za-z0-9._ -]{0,63}$), kind (required: cli, serve, daemon), version? (at most 64), max_usd? (its own cap per run, above 0 and at most 1000), can? (builtin, golden) |
claim answer (eval_job) |
id, k (1 to 10), max_usd, base_url, key, deadline (12 hours), timeout_sec, tasks ({kind: "builtin", filter: "<task ids>"} or {kind: "golden", golden: [...]}), variants (1 to 4) |
| progress body | trials_done, trials_total (required), variant?, spent_usd?, message? (at most 500) |
| result body | status (done, failed, capped), error?, variants: [{label, run}], each run a slim eval result with each task's trials (pass, wall_ms, cost_usd?, error?, checks?) |
| result answer | {object: "eval_run", id, status, verdicts: [{variant, verdict, line}]}: each variant against A, paired over shared tasks with a bootstrap 95% interval (better, worse, or no clear difference) |
A job key may not call a provider model with no price (403 unpriced_model), since a budget cannot limit it. A
result for a run that is not running answers 409 conflict. Bodies: hello and progress at most 16 KiB, a result at
most 4 MiB.
Issue intake
An issue labelled (default venom) or assigned to venom in Linear or Jira becomes a job. venom intake run is the
reference runner: it works in a worktree, opens a pull request with gh and reports; the cloud comments on the
issue and moves its status.
| Message | Fields |
|---|---|
| hello body | name, kind (as evals), version?, max_usd? (above 0, at most 100), repos (repositories this machine has, at most 50; [] = any) |
claim answer (intake_job) |
id, source (linear, jira), issue (id, key, title, url, body), repo, base_ref, branch (venom/<key>-<slug>), model, gear, thinking, max_usd, base_url, key, deadline (4 hours), timeout_sec |
| progress body | phase (required: preparing, running, pushing, opening_pr), note? (at most 500), spent_usd? |
| result body | status (required: done, no_changes, failed), pr_url? (https), branch?, summary? (at most 4,000), error? (at most 2,000), cost_usd? (at most 64 KiB in all) |
A claim takes only a job whose cap fits the runner's max_usd. A failed job whose bookings reached the cap ends
capped. The issue's comment is posted after the response.
Red-team runs
POST /v1/redteam/runs is venom redteam run against Venom Cloud (see Red team). The
corpus's free cases run in the cloud on the key's guardrails (the org's, the key group's and the member's own); the model
cases, which cost money, run in the client through the org's routing and come with the request.
curl -s "$VENOM_CLOUD/v1/redteam/runs" -H "Authorization: Bearer $VENOM_KEY" \
-H "Content-Type: application/json" -d '{"gear": "strong", "dry_run": true}'| Field | Type | Default | Notes |
|---|---|---|---|
gear |
string | none | the gear the model cases ran under, at most 100 characters |
model_results |
array | [] |
at most 100, each a model case of the current corpus once: {id, status: "pass" | "fail" | "skipped", code?, evidence?}; code is the guardrail code that caught it |
cost_usd |
number | 0 | what the model cases cost |
dry_run |
boolean | false | true: score and return the run without keeping it |
The answer is {object: "redteam.run", ...} with the totals (passed, failed, skipped), the per-category scores
and every case's result (id, category, check, status, caught_by, evidence, suggest?). A kept run appears
on the console's Red team page. Model cases not sent come back skipped. A case caught by a member's personal
guardrail is reported without naming the rule. Bad model_results is 400 invalid_request.
Errors
| Status | code |
Where |
|---|---|---|
| 400 | invalid_request, arm_mismatch |
bad bodies |
| 403 | unpriced_model |
an eval job key calling an unpriced provider model |
| 404 | not_found, version_not_found, no_bundle, gear_not_found |
unknown or out-of-scope ids, marketplace versions, gears |
| 409 | memory_queue_full, version_pinned, no_gear, conflict |
memory, marketplace, knowledge, eval results |
| 410 | runner_removed |
a runner an admin removed |
| 422 | secrets_found |
a memory proposal that matches a secret pattern |
| 429 | too_many_proposals |
more than 20 memory proposals a day from one key |
| 502 | empty_answer |
the knowledge model returned nothing |
| 503 | policy_signing_not_configured |
marketplace manifests without a signing key |
Related
- Venom Cloud APIs overview: credentials, errors, limits and headers
- Sessions API: shares, live sessions, handoffs and serve sessions
- Team library, Installing plugins, Red team