Skip to content
Docs menu

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.

View .md

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"}
]}
  • items are 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. scope is repo when the fact has a repository pattern, else team or org.
  • repo is a pattern matched by the client against its normalized origin remote (github.com/acme/web): * matches within one path segment, ** across segments. A pattern whose first segment has no dot matches after any host (acme/web matches github.com/acme/web and gitlab.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. sha256 is the SHA-256 of the version's content as canonical JSON. required: true asks the client to always load the item.
  • A prompt under a running A/B test carries experiment (id, name, split, ends_at and both arms' body, argument_hint, params, version, sha256) for keys in the test's audience. The client puts a session in arm b when the first 4 bytes of sha256("<id>:<session id>"), as a big-endian integer mod 10000, are below split × 100, else a.
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": "…"}
  • sig is Ed25519 over the canonical JSON without sig, with the key that signs the org's policy (the one venom cloud login pinned). Check it, expires_at (15 minutes after issue), tenant_id and name before you use the listing. No signing key: 503 policy_signing_not_configured.
  • source is {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 is 404 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:

  1. Hello. POST /v1/{evals|intake}/runners registers 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_removed when an admin removed that name.
  2. Claim. POST /v1/{evals|intake}/runners/{id}/claim (no body) hands over the oldest queued job, or 204. The job carries base_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 a purpose so its spend is booked apart. Use that key, never your own, for the job's model calls.
  3. Progress. POST /v1/{evals|intake}/jobs/{id}/progress at least every 15 seconds renews a 3-minute lease and answers {stop, reason?, spent_usd, cap_usd}. Stop when stop is true: reason is cancelled, capped (the key's bookings reached the cap) or lost (the lease ran out).
  4. Result. POST /v1/{evals|intake}/jobs/{id}/result ends 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