# Venom documentation > Venom is the operating layer for human and AI teams: a workspace of apps (notes, tasks, people, support, chat, forms, flags, experiments, incidents, comms) with agents as members, the venom coding agent and its harness library, and a self-hosted OpenAI-compatible orchestrator under them. It runs in Venom Cloud, in your cloud or on your servers. Source: https://cloud.usevenom.dev/docs. Each page below starts with a line of ===, its title and its URL. ================================================================================ # Getting started URL: https://cloud.usevenom.dev/docs/getting-started Description: Pick where to start with venom, whether you use the CLI, run your own models, use Venom Cloud or build an app on the harness. Venom is the agent-native operating layer you own: a workspace of apps for people and agents, priced on usage and outcomes instead of seats, a coding agent, and the model infrastructure under them, on models and machines you choose. It runs in Venom Cloud, in your cloud or on your servers; [Choose how to run Venom](/docs/getting-started/choose-how-to-run.md) compares them, and [Products](/docs/products.md) lists every product. The coding agent works with no one else's servers, and every piece works on its own: | Piece | What it is | Start here | |---|---|---| | venom CLI | A coding agent for your terminal, under permission rules you set, with an OS sandbox on macOS and Linux. | [venom CLI quickstart](/docs/getting-started/cli-quickstart.md) | | Venom Cloud | One OpenAI-compatible endpoint for your own GPUs, trusted public nodes and provider keys, with keys, budgets and logs per key group. | [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md) | | Orchestrator | A self-hosted OpenAI-compatible gateway in Go in front of vLLM, SGLang, llama.cpp, Ollama and cloud providers. | [Local or cloud models](/docs/getting-started/local-or-cloud.md#orchestrator), then the [Orchestrator API](/docs/api/orchestrator) | | Desktop daemon | The orchestrator and a dashboard on your own machine, without Docker, for local models. | [Local or cloud models](/docs/getting-started/local-or-cloud.md#daemon) | | Harness and `venom serve` | The agent harness as a library, and the same sessions over HTTP with Server-Sent Events, for building your own agent apps. | [Harness server API](/docs/api/harness-server) | ## The path through this section {#path} 1. [Install venom](/docs/getting-started/install.md) on macOS, Linux or Windows. 2. [Local or cloud models](/docs/getting-started/local-or-cloud.md): point venom at Ollama, your own orchestrator, Venom Cloud or a provider. 3. [venom CLI quickstart](/docs/getting-started/cli-quickstart.md): a first session, permission modes and `venom doctor`. 4. [Your first gear](/docs/getting-started/first-gear.md): switch between cheap, strong and local models in one keystroke. 5. [Troubleshooting](/docs/getting-started/troubleshooting.md) when something doesn't work. The shortest version, for a machine with Ollama: ```bash curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh export PATH="$HOME/.venom/bin:$PATH" ollama pull qwen3:8b export VENOM_BASE_URL=http://localhost:11434/v1 cd ~/work/app && venom ``` ## Building an app on venom {#builders} The harness that runs venom's agent loop, permissions, subagents and Claude Code compatibility is a separate library, so you can build your own product on it (a support desk, a collections workflow, an internal tool) without the terminal UI. Two ways in: - **In Node:** embed `@venom/harness` and drive sessions from your code. The [Harness section](/docs/harness.md) covers it. - **From any language:** run `venom serve` and use its HTTP API with Server-Sent Events; there is a Python client. The generated reference is at `/docs/api/harness-server`. Either way the models come from the same endpoint choices as the CLI: see [Local or cloud models](/docs/getting-started/local-or-cloud.md). ## For agents Every page here is also plain markdown: add `.md` to its URL (for example `/docs/getting-started/cli-quickstart.md`). [`/docs/llms.txt`](/docs/llms.txt) lists every page with a one-line description, and [`/docs/llms-full.txt`](/docs/llms-full.txt) has all of them in one file. ## In this section {#in-this-section} - [Choose how to run Venom](/docs/getting-started/choose-how-to-run.md): Compare Venom Cloud, your own cloud and your own servers or an air-gapped site, where the data lives in each, what can leave, and where the install guides are. - [venom CLI quickstart](/docs/getting-started/cli-quickstart.md): Install the venom CLI, point it at a model, run a first session and check the setup with venom doctor. - [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md): Sign up, create an API key, install the venom CLI, point it at Venom Cloud and test it. - [Install venom](/docs/getting-started/install.md): Install, update and remove the venom CLI on macOS, Linux and Windows, from the release installer, by hand, or from source. - [Local or cloud models](/docs/getting-started/local-or-cloud.md): Choose where venom's model runs (Ollama on this machine, the desktop daemon, your own orchestrator, Venom Cloud or any OpenAI-compatible provider) and point the CLI at it. - [Your first gear](/docs/getting-started/first-gear.md): Switch between cheap, normal, strong and local models in one keystroke with gears, build a gear for your budget with the gear wizard, and make it the default. - [Troubleshooting](/docs/getting-started/troubleshooting.md): Diagnose a venom setup with venom doctor and fix the common install, endpoint, key, model, sandbox and trust problems. ================================================================================ # Choose how to run Venom URL: https://cloud.usevenom.dev/docs/getting-started/choose-how-to-run Description: Compare Venom Cloud, your own cloud and your own servers or an air-gapped site, where the data lives in each, what can leave, and where the install guides are. Venom is built as software you run, which Venom can also host for you. You pick where it runs, and that decides where your data lives. You can start in one place and move to another: the endpoint is a URL, and sessions are stored on your machine whichever one served them. ## The three ways {#ways} | | Venom Cloud | Your cloud | Your servers or air-gapped | |---|---|---|---| | Who runs the control plane | Venom | You, on your cloud account | You, on hardware you own | | Where the workspace data lives | In Venom Cloud's database | In your database | On your servers | | Where prompts go | The target your routing policy picks | The same, from your deployment | Your own model servers; nothing else if you add no cloud key | | What you set up | Sign up and create a key | Deploy the cloud app and a database | Docker Compose, Kubernetes or the air-gapped bundle | | Works with the network unplugged | No | No, unless the model servers are inside your network | Yes, with local models | ### Venom Cloud {#cloud} The hosted version. You sign up and get one OpenAI-compatible endpoint, the workspace apps and a console. Workspace data (notes, tasks, people and so on) is stored in Venom Cloud's database. Your GPUs stay yours: a daemon in mesh mode dials out to the cloud and keeps its provider keys and models local, and a request either passes through the cloud in transit or is redirected straight to your daemon with a single-use ticket. Start with the [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md). ### Your cloud {#byoc} The same control plane and apps, deployed on a cloud account you own, with your own database. Workspace data never reaches Venom's servers, and the deployment keeps running if you stop paying. [Self-hosting Venom Cloud](/docs/cloud/self-hosting.md) lists the variables and make targets, and [Deploy](/docs/deploy.md) covers the orchestrator and the daemons that serve models for it. Install guides for a one-command Linux server and a one-click AWS launch are being written; until then, this is the path. ### Your servers or air-gapped {#servers} The orchestrator and console on hardware you control, from one machine to a Kubernetes cluster, in front of vLLM, SGLang, llama.cpp or Ollama. With no cloud key set, no request leaves your network. For a site with no network at all, the [air-gapped install](/docs/deploy/airgap.md) is built on a connected machine once and carried across. Guides: [Docker Compose](/docs/deploy/compose.md), [Kubernetes](/docs/deploy/kubernetes.md), [the desktop daemon](/docs/deploy/desktop-daemon.md), [air-gapped](/docs/deploy/airgap.md). ## What leaves {#leaves} Whichever way you run it, two things can leave your infrastructure, and both are off until you turn them on: - **Model calls to external providers.** A request goes to OpenAI, Anthropic or another provider only when your routing policy allows that provider and you have given it a key. A private route sends nothing outside your own daemons. - **Update checks.** Venom ships with no telemetry. The desktop daemon's auto-update is a dashboard switch, off until you flip it, and makes one request for a checksum file per check. Mesh mode only exists when you set `VENOM_CLOUD_URL`; without it a daemon dials nothing. ## Which one to pick {#pick} - You want to be running in five minutes, and you are fine with workspace data in Venom Cloud: **Venom Cloud**. - Your data may not leave your own account or region, but you have a cloud team: **your cloud**. - You have your own GPUs, a compliance boundary, or no network: **your servers or air-gapped**. To use only the coding agent, skip all of this: [install the venom CLI](/docs/getting-started/install.md) and point it at a local model. See every product on the [Products](/docs/products.md) page. ================================================================================ # venom CLI quickstart URL: https://cloud.usevenom.dev/docs/getting-started/cli-quickstart Description: Install the venom CLI, point it at a model, run a first session and check the setup with venom doctor. From nothing to a first session in a few minutes. The [CLI page](/cli) has the downloads. ## Install {#install} On macOS or Linux: ```bash curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh ``` The script picks the build for your OS and chip, downloads it and `SHA256SUMS` from the [public releases repository](https://github.com/elishahbiz/venom-releases/releases/latest), checks the hash, unpacks it and links `~/.venom/bin/venom`. If `~/.venom/bin` is not on your PATH it prints the line to add. Each build includes its own Node runtime, so nothing else is needed. To install by hand, download the archive for your platform, check it with `shasum -a 256 -c SHA256SUMS --ignore-missing`, unpack it anywhere and run `bin/venom`. [Install venom](/docs/getting-started/install.md) covers the installer's options, Windows, updates, uninstalling and building from source. ```bash venom --version ``` ## Pick a model {#model} venom speaks the OpenAI API. `VENOM_BASE_URL` says where to send requests, `VENOM_API_KEY` is the key for that endpoint (if it needs one) and `VENOM_MODEL` picks the model. Put the exports in your shell profile to keep them. Offline, with Ollama on your machine: ```bash ollama pull qwen3:8b export VENOM_BASE_URL=http://localhost:11434/v1 export VENOM_MODEL=qwen3:8b ``` With Venom Cloud, using a `vck_` key from the console ([cloud quickstart](/docs/getting-started/cloud-quickstart.md) has the steps): ```bash export VENOM_BASE_URL=https://cloud.usevenom.dev/v1 export VENOM_API_KEY=vck_… ``` Any other OpenAI-compatible endpoint (vLLM, SGLang, llama.cpp, a gateway or a provider) works the same way: its base URL including `/v1`, its key and a model it serves. | Variable | What it sets | Default | |---|---|---| | `VENOM_BASE_URL` | The OpenAI-compatible endpoint, including `/v1` | `http://localhost:8787/v1` (a local orchestrator) | | `VENOM_API_KEY` | The key for that endpoint | none (no `Authorization` header) | | `VENOM_MODEL` | The model to use | `venom-default` (the orchestrator's default alias) | [Local or cloud models](/docs/getting-started/local-or-cloud.md) compares the options (Ollama, the desktop daemon, your own orchestrator, Venom Cloud, a provider) and shows how to save the endpoint in `~/.venom/config.yaml` instead of exporting it. ## A first session {#session} Start venom in your project: ```bash cd ~/work/app venom # the interactive agent venom -p "explain this repo" # one prompt, printed answer venom -c # continue the last session here ``` `venom init` proposes an `AGENTS.md` and starter permission rules for the project. If the project is set up for Claude Code, venom reads its `CLAUDE.md`, skills, commands, agents, settings and `.mcp.json` as they are. Hooks, MCP servers and allow rules from a project take effect only once you trust it; venom asks the first time. ### What the first run looks like {#first-run} 1. **Trust.** In a project that ships configuration that can run code or loosen permissions (hooks, MCP servers, allow rules, plugins), venom lists what would run and asks: Trust this project, Trust parent folder, Don't trust (ignore it), or Decide later. Until you trust it, venom ignores those items and runs with your own settings only. `venom trust` asks the same question from a shell (`venom trust --yes` without a terminal), `venom trust --list` shows your decisions and `venom trust --revoke` undoes one. `--approve` trusts a project for one run. 2. **The prompt.** Type a request and press Enter. The agent reads files, runs commands and edits; anything your mode and rules don't allow asks you first. Esc stops the current turn. 3. **The status bar** at the bottom shows the directory and git branch, then the permission mode and sandbox, the context window used, running subagents, the session's cost and tokens, and the model with its thinking level: ```text ~/work/app ⎇ main ⏵ edits sbx ctx 42% 2 agents 1 wait $0.012 12k↑ 3.1k↓ 50k⚡ gpt-5.4-mini high ``` Useful from the start: `ctrl+g ?` lists every key binding, typing `/` lists the slash commands, `/model` switches models, `/undo` takes back the last file change, and `/context` and `/cost` show what the session holds and has spent. To switch between cheap and strong models in one keystroke, see [Your first gear](/docs/getting-started/first-gear.md). ## Permission modes {#modes} Switch with `alt+m` or `/mode`. Rules apply as deny, then ask, then allow. Shell commands are parsed, and each part of a compound command is judged on its own. A short list of destructive commands (such as `rm -rf ~` or piping `curl` into a shell) is denied in every mode. | Mode | What it allows | |---|---| | `plan` | Read-only. The agent explores and proposes a plan; no file changes, no commands that write. | | `default` | Edits and commands your rules don't allow ask you first. | | `accept-edits` | Edits in the workspace go ahead; commands still ask. | | `yolo` | Runs without asking. Bash runs inside the OS sandbox on macOS and Linux: writes stay in the workspace and temp dirs, network through an allowlist. | Your own rules live in `~/.venom/permissions.json`; settings in `~/.venom/config.yaml`, or a `venom.yaml` in the project. ## Check the setup {#doctor} ```bash venom doctor ``` It checks the endpoint (reachable, your key, the models and their context windows), the OS sandbox, what the current project loads and where your prompts go, and prints PASS, WARN or FAIL with a fix on each line. `venom doctor --probe` also sends the model a short chat and a tool call. [Troubleshooting](/docs/getting-started/troubleshooting.md) lists every flag and the common failures. ## Update {#update} Run the install line again; it installs the newest release next to the old one and moves the link. Set `VENOM_VERSION` to install a specific version. ## Windows (beta) {#windows} In PowerShell: ```powershell irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex ``` It installs to `%USERPROFILE%\.venom\bin` and adds that to your user PATH. Windows has no OS sandbox, and venom says so when it starts: in yolo, commands your rules don't allow still ask, and auto mode is unavailable. For the full sandbox, run the Linux build in WSL. ## Next steps - [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md): one endpoint for your GPUs, trusted public nodes and provider keys. - [Your first gear](/docs/getting-started/first-gear.md): presets of models you switch with `ctrl+g` and a number. - [Troubleshooting](/docs/getting-started/troubleshooting.md): `venom doctor` and the common problems. - [API reference](/docs/api): the HTTP APIs of `venom serve`, the orchestrator and Venom Cloud. ================================================================================ # Venom Cloud quickstart URL: https://cloud.usevenom.dev/docs/getting-started/cloud-quickstart Description: Sign up, create an API key, install the venom CLI, point it at Venom Cloud and test it. Four steps from a new account to a first answer. The console walks you through the same steps on its Get started page. ## Create an account {#account} [Sign up](/auth/clerk/sign-up) and name your organisation. You are its owner. The console then opens Get started; you can come back to it later from Settings or the API keys page (or [sign in](/login) and open `/get-started`). ## Create an API key {#key} On Get started, name the key (who or what uses it, such as `alice-laptop`) and create it. Keys start with `vck_`. The console shows a key once: copy it then. A lost key can't be shown again; revoke it under Settings, API keys, and make another. ## Install, connect and test {#install} On macOS or Linux, paste this into a terminal, with your key in place of `vck_…`. Get started shows it with the key already filled in. ```bash # 1. Install the venom CLI curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh export PATH="$HOME/.venom/bin:$PATH" # 2. Point it at Venom Cloud export VENOM_BASE_URL=https://cloud.usevenom.dev/v1 export VENOM_API_KEY=vck_… # 3. Test it: checks the endpoint and the key, then one prompt venom doctor venom -p "Reply with the single word: ready" ``` The installer checks the download against its `SHA256SUMS` and links `~/.venom/bin/venom`. `VENOM_BASE_URL` is this cloud's OpenAI-compatible endpoint, including `/v1`, and `VENOM_API_KEY` is your key. `venom doctor` checks the endpoint, the key and the models and prints PASS, WARN or FAIL with a fix on each line; the prompt after it should answer "ready". Windows and other install options are in the [CLI quickstart](/docs/getting-started/cli-quickstart.md). To check the key without the CLI, list the models it may use: ```bash curl https://cloud.usevenom.dev/v1/models \ -H "Authorization: Bearer vck_…" ``` ## Keep the setting {#keep} The exports last for one shell. Add them to `~/.zshrc` or `~/.bashrc`: ```bash export PATH="$HOME/.venom/bin:$PATH" export VENOM_BASE_URL=https://cloud.usevenom.dev/v1 export VENOM_API_KEY=vck_… ``` Then run `venom` in a project. Requests show up in the console under Requests, by key name. ## Troubleshooting | Symptom | Cause and fix | |---|---| | `401` from `/v1/models` | The key is wrong, revoked or missing its `vck_` prefix. Create a new one under Settings, API keys. | | `venom: command not found` | `~/.venom/bin` is not on your PATH. Run the `export PATH=…` line, or add it to your shell profile. | | `venom doctor` FAILs on the endpoint | Check `VENOM_BASE_URL` ends in `/v1` and has no trailing slash. | ## Related - [Venom Cloud API](/docs/api/cloud): every `/v1` route, its auth and a curl line. - [venom CLI quickstart](/docs/getting-started/cli-quickstart.md): models, permission modes, updates and Windows. ================================================================================ # Install venom URL: https://cloud.usevenom.dev/docs/getting-started/install Description: Install, update and remove the venom CLI on macOS, Linux and Windows, from the release installer, by hand, or from source. The venom CLI ships as one archive per platform. Each archive carries its own Node.js runtime, so it needs nothing else installed, and the installers never ask for root or administrator rights. Every download comes from the [public releases repository](https://github.com/elishahbiz/venom-releases/releases) and is checked against the release's `SHA256SUMS` before anything is unpacked. ## Supported platforms {#platforms} | OS | Chips | Archive | Notes | |---|---|---|---| | macOS | Apple silicon (`arm64`), Intel (`x64`) | `venom--darwin-.tar.gz` | An x64 shell under Rosetta still gets the native `arm64` build. OS sandbox: Seatbelt (`sandbox-exec`). | | Linux (glibc) | `x64`, `arm64` | `venom--linux-.tar.gz` | musl systems such as Alpine are not supported yet. OS sandbox: bubblewrap (`bwrap`), which you install from your distribution. | | Windows (beta) | `x64`; ARM64 runs the x64 build under emulation | `venom--windows-x64.zip` | No OS sandbox. For the full sandbox, run the Linux build in WSL. | ## macOS and Linux {#unix} ```bash curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh | sh ``` The script: 1. picks the build for your OS and chip (`uname -s`, `uname -m`); 2. downloads the release's `SHA256SUMS`, finds the archive for your platform in it, downloads that archive from its version's own URL and compares the SHA-256. On a mismatch it stops and installs nothing; 3. unpacks it into `~/.venom/releases/venom---/`, removes the macOS quarantine attribute, and links `~/.venom/bin/venom` to it; 4. runs the installed `venom --version`, and prints the line to add to your shell profile if `~/.venom/bin` is not on your PATH. It needs `curl`, `tar`, `uname`, `mktemp` and `sha256sum` or `shasum`. ### Installer variables {#installer-env} | Variable | Default | What it does | |---|---|---| | `VENOM_VERSION` | the latest release | Install this version instead, for example `VENOM_VERSION=0.4.2`. A leading `v` is accepted. | | `VENOM_INSTALL_DIR` | `~/.venom` | Where releases are unpacked (in `releases/` under it). | | `VENOM_BIN_DIR` | `$VENOM_INSTALL_DIR/bin` | Where the `venom` link goes, for example `/usr/local/bin` if you can write there. | ```bash curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.sh \ | VENOM_VERSION=0.4.2 VENOM_BIN_DIR="$HOME/.local/bin" sh ``` ### Put venom on your PATH {#path} If the installer said `~/.venom/bin is not on your PATH`, add it to your shell's startup file: ```bash echo 'export PATH="$HOME/.venom/bin:$PATH"' >> ~/.zshrc && exec zsh # zsh (macOS default) echo 'export PATH="$HOME/.venom/bin:$PATH"' >> ~/.bashrc && exec bash # bash fish_add_path ~/.venom/bin # fish ``` ### The Linux sandbox {#bubblewrap} On Linux, venom's OS sandbox is bubblewrap. Without it, yolo mode asks before shell commands the way accept-edits does, and `venom doctor` warns. Install it once: ```bash sudo apt-get install -y bubblewrap # Debian, Ubuntu sudo dnf install -y bubblewrap # Fedora, RHEL ``` macOS has its sandbox (`sandbox-exec`) built in. ## Windows (beta) {#windows} In PowerShell (no administrator rights needed): ```powershell irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install.ps1 | iex ``` It does the same checks as the shell installer, unpacks the zip into `%USERPROFILE%\.venom\releases\`, writes a small `venom.cmd` shim into `%USERPROFILE%\.venom\bin` and adds that directory to your user PATH. New terminals pick up the PATH change; the current one is updated too. `$env:VENOM_VERSION` and `$env:VENOM_INSTALL_DIR` work as on macOS and Linux. Windows has no OS sandbox, and venom says so at start: in yolo mode, shell commands your rules don't allow still ask, and auto mode is unavailable. Everything else works. For the sandbox, install the Linux build inside WSL with the shell installer. Set the endpoint for the current PowerShell session like this (see [Local or cloud](/docs/getting-started/local-or-cloud.md) for which one): ```powershell $env:VENOM_BASE_URL = "https://cloud.usevenom.dev/v1" $env:VENOM_API_KEY = "vck_…" venom doctor ``` To keep them, use `setx VENOM_BASE_URL "…"` (new terminals only), or set them in your PowerShell profile. ## By hand {#manual} Download the archive for your platform and `SHA256SUMS` from the [latest release](https://github.com/elishahbiz/venom-releases/releases/latest), then: ```bash shasum -a 256 -c SHA256SUMS --ignore-missing # or: sha256sum -c SHA256SUMS --ignore-missing tar -xzf venom-*-darwin-arm64.tar.gz ./venom-*-darwin-arm64/bin/venom --version ``` The unpacked directory runs from anywhere; link or copy `bin/venom` onto your PATH. ## Check the install {#check} ```bash venom --version venom doctor ``` `venom doctor` FAILs on the endpoint until you give venom a model. That is the next step: [Local or cloud](/docs/getting-started/local-or-cloud.md). ## Update {#update} Run the install line again. It installs the newest release next to the old one in `~/.venom/releases/` and moves the link, so a running session keeps working. `venom doctor --check-update` compares your version with the latest release (one small request to GitHub; venom never checks on its own). To go back to an older version, install it with `VENOM_VERSION`, or point the link at a directory that is still in `~/.venom/releases/`. ## Uninstall {#uninstall} ```bash rm -f ~/.venom/bin/venom rm -rf ~/.venom/releases ``` `~/.venom/` also holds your settings and history: `config.yaml`, `permissions.json`, sessions under `agent/`, checkpoints, and `cloud.json` after `venom cloud login`. Delete the whole directory to remove those too. On Windows, delete `%USERPROFILE%\.venom` and remove its `bin` entry from your user PATH. ## Other ways to run venom {#other} | Want | Use | |---|---| | Local models on this machine without Docker, with a dashboard | The desktop daemon: `curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.sh \| sh` (Windows: `install-daemon.ps1`). It runs the orchestrator and console on `127.0.0.1`. See [Local or cloud](/docs/getting-started/local-or-cloud.md#daemon). | | A machine with no internet | The air-gapped bundle, built from a source checkout with `make release` then `make airgap` on a connected machine, carried over and installed with its own `install.sh` (no network). | | To change venom itself | A source checkout (below). | ### From source {#source} You need Node.js 22.19 or newer for the CLI, Docker plus Go 1.24 or newer for the orchestrator, and bun 1.4.2, which installs the JavaScript packages and runs their scripts (`make` opens a devbox shell with Go, Node and bun). ```bash git clone venom && cd venom make env # creates .env (mode 600) from .env.example make up # orchestrator on 127.0.0.1:8787, console on http://localhost:3000 make link-cli # builds the CLI and puts `venom` on your PATH (a link in npm's global bin dir) export VENOM_API_KEY=$(grep '^VENOM_API_KEY=' .env | cut -d= -f2-) venom doctor ``` The CLI does not read `.env`: export the same `VENOM_API_KEY` the orchestrator got from it, or every request gets a 401. If `make link-cli` fails with `EACCES` (inside devbox or a Nix shell), `venom doctor --fix` links `venom` into a writable directory on your PATH instead. `make release VERSION=x.y.z` builds the same archives the public releases ship, into `dist/release//`. ## Related - [Local or cloud](/docs/getting-started/local-or-cloud.md): give venom a model. - [venom CLI quickstart](/docs/getting-started/cli-quickstart.md): the shortest path to a first session. - [Troubleshooting](/docs/getting-started/troubleshooting.md): `venom doctor` and the common failures. ================================================================================ # Local or cloud models URL: https://cloud.usevenom.dev/docs/getting-started/local-or-cloud Description: Choose where venom's model runs (Ollama on this machine, the desktop daemon, your own orchestrator, Venom Cloud or any OpenAI-compatible provider) and point the CLI at it. venom talks to one OpenAI-compatible endpoint. Three settings decide which one and what it asks for: | Variable | What it sets | Default | |---|---|---| | `VENOM_BASE_URL` | The endpoint, including `/v1` | `http://localhost:8787/v1` (an orchestrator on this machine) | | `VENOM_API_KEY` | The key for that endpoint, sent as `Authorization: Bearer` | none (no header) | | `VENOM_MODEL` | The main model | `venom-default` | The rest of this page is about picking the endpoint. Your code, prompts and files go only to the endpoint you choose. venom makes no other calls: no telemetry, no update checks. ## Pick one {#choose} | Option | What runs where | Good for | Cost | |---|---|---|---| | [Ollama, direct](#ollama) | Ollama on this machine, nothing else | Trying venom offline in two minutes | Free; needs RAM or a GPU | | [Desktop daemon](#daemon) | venom's orchestrator and dashboard on `127.0.0.1`, in front of Ollama | Local models with routing, fallbacks, a request log and a UI, without Docker | Free | | [Your own orchestrator](#orchestrator) | The Go orchestrator in Docker or on a server, in front of vLLM, SGLang, llama.cpp, Ollama and your provider keys | Teams and GPU servers; mixing local and cloud models with fallback | Your hardware and your provider bills | | [Venom Cloud](#cloud) | One hosted endpoint; requests go to your own daemons, trusted public nodes or provider keys | No setup; keys, budgets and logs per key group | Per token, by model | | [Any provider](#provider) | A provider's or gateway's OpenAI-compatible API | You already have a key | That provider's prices | You can switch at any time: the endpoint is read when venom starts, and sessions are stored on your machine whichever endpoint served them. ## Ollama, direct {#ollama} ```bash ollama pull qwen3:8b ollama pull qwen3:4b export VENOM_BASE_URL=http://localhost:11434/v1 venom ``` When the server lists no `venom-*` aliases, venom makes its own from the models it lists: one model serves all three tiers; with several, it ranks them by the parameter count in the id (`4b`, `8b`, `32b`) and then by size words (nano, mini, large, pro), so `venom-default` and `venom-smart` take the larger model and `venom-fast` (subagents, summaries) the smaller. With more than 12 models, or ids it cannot rank, it asks you to set the map yourself: ```bash export VENOM_MODEL=qwen3:8b export VENOM_ALIAS_MAP=venom-fast=qwen3:4b,venom-smart=qwen3:8b ``` Use models that emit structured tool calls (the qwen3 family does); `venom doctor --probe` checks it. Ollama truncates prompts longer than its context length without saying so; start it with a window that fits a coding session, for example `OLLAMA_CONTEXT_LENGTH=32768 ollama serve`, and set `VENOM_CONTEXT_WINDOW=32768` so venom compacts in time. ## The desktop daemon {#daemon} The daemon is venom's orchestrator and console packaged for a desktop or a GPU box, with no Docker: ```bash curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.sh | sh ``` On Windows: `irm https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-daemon.ps1 | iex`. It installs `venom-daemon`, starts the orchestrator and the console on `127.0.0.1`, and opens the dashboard signed in. From the dashboard you install Ollama (a link to its download page), pull the models that fit this machine, and optionally connect the machine to Venom Cloud with a join token. To point the CLI at it: ```bash venom-daemon status # prints the /v1 URL and the secrets file export VENOM_BASE_URL=http://127.0.0.1:8787/v1 export VENOM_API_KEY=… # client_key in ~/.venom/daemon/secrets.json ``` The port is `8787` unless it was taken, in which case `venom-daemon status` shows the one it picked. The secrets file is `%LOCALAPPDATA%\Venom\secrets.json` on Windows. ## Your own orchestrator {#orchestrator} The orchestrator is the OpenAI-compatible gateway venom is designed around. It serves the aliases `venom-default`, `venom-fast` and `venom-smart`, routes each to the first healthy target (a local engine first, a cloud model as fallback), keeps a session on the same backend so its prompt cache is reused, and logs usage and cost in SQLite. Its default address is the CLI's default, so on the same machine only the key is needed: ```bash export VENOM_API_KEY=… # a client key the orchestrator accepts (VENOM_API_KEY in its .env) venom doctor ``` From a source checkout, `make up` runs it in Docker and `make model` picks a local model; a release install runs it as `venom-orchestrator`. Provider keys such as `OPENAI_API_KEY` stay in the orchestrator's environment, never in the CLI's. The [Orchestrator section](/docs/orchestrator.md) covers upstreams, routes and profiles. ## Venom Cloud {#cloud} ```bash export VENOM_BASE_URL=https://cloud.usevenom.dev/v1 export VENOM_API_KEY=vck_… venom doctor ``` The [Venom Cloud quickstart](/docs/getting-started/cloud-quickstart.md) has the sign-up and key steps. Separately, `venom cloud login` signs this machine in for the team features (the fleet view, shared sessions, the org policy, org MCP servers): it opens a device-code page in the browser and saves a key in `~/.venom/cloud.json`. It does not change `VENOM_BASE_URL`; set that as above to send model requests to the cloud. `venom cloud status` shows the login, and `venom cloud logout` removes it. ## Any OpenAI-compatible provider {#provider} ```bash export VENOM_BASE_URL=https://api.openai.com/v1 export VENOM_API_KEY=sk-… venom ``` On `api.openai.com` venom maps `venom-default`, `venom-fast` and `venom-smart` to `gpt-5.4-mini`, `gpt-5.4-nano` and `gpt-5.5`. Elsewhere (vLLM, SGLang, llama.cpp's server, a gateway) it ranks the listed models as described for Ollama; set `VENOM_MODEL` and `VENOM_ALIAS_MAP` when it can't. Without the orchestrator you lose its fallback, routing and request log, and the key sits in the CLI's environment. ## Keep the setting {#persist} Exports last one shell. Either add them to `~/.zshrc` or `~/.bashrc`, or save the endpoint in venom's config file, which every venom command reads: ```bash venom config set orchestrator.base_url https://cloud.usevenom.dev/v1 venom config set model venom-default ``` That writes `~/.venom/config.yaml`. Keys are never read from the config file: `VENOM_API_KEY` stays an environment variable. An environment variable wins over the config file, and `--model` wins over both. ## Which model a session uses {#model-order} Every command, the TUI and `venom -p` included, picks its model in this order: `--model`, then `VENOM_MODEL` (or `model:` in the config file), then the model `/model` saved last time (`defaultModel` in `~/.venom/agent/settings.json`), then `venom-default`. A session you reopen with `venom -c`, `-r` or `--session` keeps the model it was using. Subagents and summaries use the fast tier: `venom-fast` when the endpoint lists it, otherwise the session's model, unless `VENOM_FAST_MODEL` names another. ## Offline {#offline} `venom --offline` (or `VENOM_OFFLINE=1`) removes the web tools (`web_fetch`, `web_search`) and disables remote MCP servers for the run. With a local endpoint, nothing leaves the machine. With an orchestrator on this machine, venom also notices when a cloud upstream stops answering mid-session and moves the session to the local gear; see [Your first gear](/docs/getting-started/first-gear.md). ## Related - [Your first gear](/docs/getting-started/first-gear.md): switch models and tiers in one keystroke. - [Troubleshooting](/docs/getting-started/troubleshooting.md): endpoint and key failures. - [Install venom](/docs/getting-started/install.md). ================================================================================ # Your first gear URL: https://cloud.usevenom.dev/docs/getting-started/first-gear Description: Switch between cheap, normal, strong and local models in one keystroke with gears, build a gear for your budget with the gear wizard, and make it the default. A gear is a preset: the main model, its thinking level, the models subagents and summaries use, the vision model and the orchestrator route profile, switched together. Shifting gears is how you trade cost for strength in the middle of a task, the way you shift a car. ## Shift gears {#shift} In the TUI, press the leader key `ctrl+g`, let go, then a number: ```text ctrl+g 1 eco (cheapest) ctrl+g 2 normal ctrl+g 3 power (strongest) ctrl+g 4 local (Ollama only, fully offline) ctrl+g g pick from a list ctrl+g + one gear up ctrl+g - one gear down ``` `/gear` lists the gears, marks the engaged one and says why any are unavailable; `/gear power`, `/gear 3`, `/gear up` and `/gear down` shift. Where your terminal sends them, `alt+1` to `alt+9`, `alt+.` (up) and `alt+,` (down) and `shift+F1` to `shift+F12` work without the leader. The status bar shows the engaged gear. ## The built-in gears {#builtin} | Key | Gear | Main model (first one the endpoint serves) | Thinking | For | |---|---|---|---|---| | 1 | `eco` | `venom-fast`, `openai/gpt-5.4-nano`, `qwen-fast`, `glm-fast` | off | Reading, small edits, long cheap runs | | 2 | `normal` | `venom-default` | medium | Everyday work | | 3 | `power` | `openai/gpt-5.5`, `venom-smart`, `qwen`, `glm` | high | Hard bugs, design, large refactors | | 4 | `local` | `ollama/qwen3:8b`, then any `ollama/` model | off | Offline; nothing leaves the machine | | 5 | `delegate` | `openai/gpt-5.5`, `venom-smart`, `venom-default` | medium | A strong main model that hands work to cheap subagents eagerly | | 6 | `open` | `glm`, `kimi`, `deepseek`, `qwen` | medium | Open-weight models on Model Studio or Z.ai | | 7 | `qwen` | `qwen` | medium | Qwen first for every role | | 8 | `china` | `glm`, `kimi`, `deepseek`, `qwen` | medium | Chinese-developed models only, enforced by the orchestrator | | 9 | `auto` | `venom-auto` | medium | Venom Cloud picks the model per request | A gear whose models the endpoint doesn't serve, or whose route profile the orchestrator doesn't have, is unavailable: `/gear` shows it with the reason and shifting up or down skips it. Checking needs no request: venom uses the model list it fetched at start. When you engage a gear, venom asks the endpoint to load that gear's models (`POST /v1/prewarm`), so the first turn on a local model doesn't wait for it to load. ## Build a gear with the wizard {#wizard} ```bash venom gear new ``` Or `/gear new` in the TUI. Three questions, answered with the arrow keys: 1. Budget per task: low (about $0.05), medium ($0.25), high ($1), or a dollar amount. 2. Quality: good enough (quick edits), strong (everyday features) or the best (hard bugs, design). 3. Privacy: local only, no US providers, or anything the endpoint serves. The wizard reads the endpoint's model list (and its prices, when `VENOM_ADMIN_TOKEN` lets it read them; otherwise the bundled list prices, with local models free), picks a model for each role and shows the plan with an estimated cost per task: ```text Gear strong-gear: strong quality, any provider, budget $0.25 a task, thinking medium main → venom-default $0.08 (list price, US) workers → qwen/qwen3.8-flash $0.0069 (list price, non-US) smart → zai/glm-5.3 $0.03 (list price, non-US) summary → qwen/qwen3.8-flash $0.0032 (list price, non-US) est. $0.11 a task (a typical task's tokens at these prices; within budget) ``` The estimate prices one typical task's tokens, so it is for comparing gears, not a quote. When the endpoint serves nothing that fits your answers, the wizard lists the providers you could add and the environment variable each needs. It then saves the gear to `~/.venom/config.yaml` (every project) or the project's `venom.yaml`. Every question has a flag, for scripts: ```bash venom gear new --budget 0.30 --quality best --privacy no-us --name deep --save repo venom gear new --privacy local --json # print the plan as JSON, save nothing ``` | Flag | Values | Default | |---|---|---| | `--budget` | `low`, `medium`, `high`, or dollars per task | asked; `medium` without a terminal | | `--quality` | `good`, `strong`, `best` | asked; `strong` without a terminal | | `--privacy` | `local`, `no-us`, `any` | asked; `any` without a terminal | | `--name` | the gear's name | from the answers | | `--save` (or `--home`, `--repo`) | `home`, `repo`, `none` | asked; `home` without a terminal | | `--publish` | publish to your organisation's gears on Venom Cloud (needs `VENOM_CLOUD_ADMIN_KEY`) | off | | `--yes`, `-y` | ask nothing: unanswered questions take their defaults | implied without a terminal | | `--json` | print the plan as JSON and save nothing, unless `--save` is given too | off | ## Write a gear by hand {#yaml} A gear is a few lines of YAML in `~/.venom/config.yaml` or a project's `venom.yaml`: ```yaml gear: review # engaged at start gears: review: extends: power # start from a built-in model: venom-smart thinking: high key: 5 # ctrl+g 5, alt+5, shift+F5 ``` The same from the shell, without opening the file: ```bash venom gear save review --extends power --model venom-smart --thinking high --key 5 venom gear list # every gear: key, name, model, profile, what it extends venom gear show review # one gear, resolved through extends venom gear rm review # remove it (on a built-in: disable it) ``` `/gear save [key]` in the TUI saves what is in effect now (model, thinking, profile) as a gear; `/gear edit ` and `/gear rm ` change or remove one. [Gears in the Configuration section](/docs/configuration/gears.md) documents every gear key: per-role models (`workers`, `smart`, `vision`, `browser`, `classifier`, `summary`, `reflex`), service tiers, escalation and route profiles. ## Make it the default {#default} ```bash venom config set gear review ``` That sets `gear:` in `~/.venom/config.yaml`; every session starts in it. Put `gear:` in a project's `venom.yaml` to start that project's sessions in another gear. With Venom Cloud, an organisation can also define gears for its members and name a default; your own `gear:` wins over the organisation's default. ## Gears that shift on their own {#automatic} - **Budget.** A session that reaches 80% of its budget steps down to `eco` when the current run ends, once per session. - **Stuck.** When the agent edits a file back and forth or repeats the same failing call, venom shifts up one gear (`eco` to `normal` to `power`), once per session. - **Offline.** When a cloud upstream stops answering, venom moves the session to `local` and offers `/offline back` when the upstream answers again. None of these touch a model you picked yourself with `--model`, and none switch back on their own: a switch breaks the prompt cache. ## Related - [Local or cloud models](/docs/getting-started/local-or-cloud.md): the endpoint the gears' models come from. - [Troubleshooting](/docs/getting-started/troubleshooting.md). ================================================================================ # Troubleshooting URL: https://cloud.usevenom.dev/docs/getting-started/troubleshooting Description: Diagnose a venom setup with venom doctor and fix the common install, endpoint, key, model, sandbox and trust problems. Start with `venom doctor`. It checks the whole setup in a few seconds and prints one line per check, `PASS`, `WARN` or `FAIL`, each failure with its fix. The exit code is 1 when a required check fails. ```bash venom doctor # every section venom doctor --probe # also a short chat and a tool call to the model (costs one request) venom doctor --fix # then offers a fix for each problem it can repair, asking first ``` ## venom doctor {#doctor} | Flag | What it does | |---|---| | `--only ` | Run only these sections, comma-separated: `policy`, `environment`, `cloud`, `orchestrator`, `probe`, `browser`, `sandbox`, `project`, `sovereignty`. Only their failures set the exit code, and the report names the scope. | | `--probe` | Also send the model two tiny requests: a chat (time to first token) and a structured tool call. With `--only`, include `probe` in the list. | | `--model ` | The model to probe. Default: `VENOM_MODEL`, then the saved `defaultModel`, then `venom-default`. | | `--json` | The same report as JSON, with a `scope` field, for scripts. | | `--fix` | After the report, walk through a fix for each check venom can repair (link `venom` onto your PATH, write a starter config, sign in to Venom Cloud again), asking before each. Steps it can't take are printed as commands. | | `--yes`, `-y` | With `--fix`: apply every fix without asking. | | `--check-update` | Also compare your version with the latest release (one request to GitHub). | What each section checks: | Section | Checks | |---|---| | `policy` | The organisation policy in force, where it came from, and who to ask about it | | `environment` | Node version, venom's state directories, the install and PATH | | `cloud` | The Venom Cloud login (`venom cloud login`) and its key | | `orchestrator` | The endpoint is reachable, the key is accepted, the models and their context windows, upstream health and missing route models (when `VENOM_ADMIN_TOKEN` lets it read them) | | `probe` | With `--probe`: a chat and a tool call | | `browser` | Which Chrome, Edge, Chromium or Brave `--chrome` would use, and whether the default model takes images | | `sandbox` | The OS sandbox (`sandbox-exec` on macOS, `bwrap` on Linux) and that it can run a command | | `project` | What the current project loads: trust state, memory files, skills, commands, subagents, MCP servers, permission rules, hooks, plugins, language servers, config warnings | | `sovereignty` | That venom makes no startup calls (`PI_OFFLINE`), and where your prompts go: this machine, your own servers, or a cloud provider | For live diagnostics in a session, start venom with `VENOM_DEBUG=1`: it prints the harness's notes on hooks, compaction and MCP servers as they happen. ## Common problems {#problems} ### Install and start {#install} | Symptom | Cause | Fix | |---|---|---| | `venom: command not found` | `~/.venom/bin` is not on your PATH | Add `export PATH="$HOME/.venom/bin:$PATH"` to your shell profile ([Install](/docs/getting-started/install.md#path)) | | `the Linux builds need glibc` from the installer | Alpine or another musl system | Use a glibc distribution, a glibc container, or build from source | | `checksum mismatch … nothing was installed` | The download was cut or altered | Run the installer again; if it repeats, download by hand and compare with `SHA256SUMS` | | `venom needs Node.js >=22.19.0` | A source install running on an older Node (release archives bring their own) | Install Node 24 (`nvm install 24`, `fnm install 24`) | | `make link-cli` fails with `EACCES` (devbox or a Nix shell) | npm's global prefix is read-only | `venom doctor --fix` links `venom` into a writable directory on your PATH | ### Endpoint and key {#endpoint} | Symptom | Cause | Fix | |---|---|---| | `FAIL reachable … connection refused` | Nothing listens at `VENOM_BASE_URL`; the default is an orchestrator on `localhost:8787` | Start the orchestrator, Ollama or the daemon, or set `VENOM_BASE_URL` to the endpoint you use ([Local or cloud](/docs/getting-started/local-or-cloud.md)) | | `FAIL auth … 401`, or a 401 in a session | `VENOM_API_KEY` is missing or not a key the endpoint accepts | Export the right key. Venom Cloud keys start with `vck_`; for a source install, export the `VENOM_API_KEY` from `.env`; for the daemon, `client_key` in its `secrets.json` | | The endpoint check fails on Venom Cloud | `VENOM_BASE_URL` is missing `/v1` or has a trailing slash | Use `https://cloud.usevenom.dev/v1` | | `FAIL health … /readyz HTTP 503: no healthy upstream` | The orchestrator has no reachable model: Ollama is not running, no cloud key | Start Ollama and pull a model, or give the orchestrator a provider key and restart it | | `bind: address already in use` in the orchestrator's log | Another process (often a second orchestrator) holds `127.0.0.1:8787` | Stop it, or start this one with `VENOM_LISTEN=127.0.0.1:8788` and export `VENOM_BASE_URL=http://localhost:8788/v1` | | `lists no venom-* aliases … set VENOM_ALIAS_MAP` | A plain OpenAI-compatible server with many models, or ids venom can't rank | Set `VENOM_MODEL` and `VENOM_ALIAS_MAP=venom-fast=,venom-smart=` | ### Models {#models} | Symptom | Cause | Fix | |---|---|---| | A model you didn't expect | `--model` and `VENOM_MODEL` win over the model `/model` saved; a reopened session keeps its own model | `venom doctor` names the model in use and warns about a saved one the server doesn't list | | The model answers in prose instead of calling tools | The local model doesn't emit structured tool calls | Confirm with `venom doctor --probe`; switch to a qwen3-family model | | A gear is listed as unavailable | The endpoint serves none of its models, or the orchestrator lacks its route profile | `/gear` says which; pick another gear or build one with `venom gear new` ([Your first gear](/docs/getting-started/first-gear.md)) | | Long sessions forget the start, or the local model ignores instructions | Ollama truncated a prompt longer than its context length | Start Ollama with a larger `OLLAMA_CONTEXT_LENGTH` and set `VENOM_CONTEXT_WINDOW` to match | | `400 images_not_supported` | The session's model takes no images | Use a vision model, or set a vision model for text-only sessions | | A session cost more than expected | Long turns, prompt-cache churn, large tool outputs or subagents | `venom explain-cost` (or `/explain-cost`) shows turn by turn where it went | ### Spend limits and policy {#limits} | Symptom | Cause | Fix | |---|---|---| | `429 budget_exceeded` | The key's hard daily or monthly budget is used up | Wait for the reset named in the error (and the `x-venom-budget-reset` header), ask an admin to raise it, or use a local model | | `403 unpriced_model` | A key with a hard budget asked for a cloud model with no known price | Use a priced or local model, or have the operator add a price | | `… is not allowed by the organisation policy` (exit 2) | Your organisation's policy forbids that mode, flag, browser or endpoint | Use what it allows; `venom doctor` lists the policy and who to ask | ### Sandbox and trust {#sandbox} | Symptom | Cause | Fix | |---|---|---| | Bash asks in yolo mode, or venom says there is no OS sandbox | `bwrap` is missing on Linux; Windows has no sandbox | Linux: install `bubblewrap` ([Install](/docs/getting-started/install.md#bubblewrap)); Windows: use WSL | | A sandboxed `rm -rf` or `mv` of a directory fails with `Device or resource busy` (Linux) or `Operation not permitted` (macOS) | The directory is or holds a protected path: the project's `.venom/`, `.claude/` or `.mcp.json`, or a credential directory such as `~/.ssh` when the workspace is your home | Do it yourself in a terminal, or work in a directory narrower than `$HOME` | | `Project config changed since you trusted it`, or doctor shows trust as `suspended` | The project gained a hook, MCP server, allow rule or similar after you trusted it | Review it with `venom trust` and confirm (`venom trust --yes` without a terminal) | | A project's hooks, MCP servers or allow rules do nothing | You haven't trusted the project, or chose "Decide later" | Run `venom trust`, or start once with `--approve` | ## Still stuck {#more} - `venom doctor --json` gives the full report to paste into an issue (it contains no keys). - `venom --help` lists every command; `venom --help` shows a command's flags. - The [CLI](/docs/cli.md) and [Configuration](/docs/configuration.md) sections have the full reference. ## Related - [Install venom](/docs/getting-started/install.md) - [Local or cloud models](/docs/getting-started/local-or-cloud.md) - [Your first gear](/docs/getting-started/first-gear.md) ================================================================================ # Products URL: https://cloud.usevenom.dev/docs/products Description: Every Venom product in one page, what each is for, its MCP endpoint and whether it is an add-on, from the workspace apps to the CLI, the orchestrator, the desktop daemon and the editor clients. Venom is the agent-native operating layer you own: one workspace for your team, priced on usage and outcomes instead of seats, running on models and machines you choose, and still working when a provider fails or raises its prices. It runs in Venom Cloud, in your cloud or on your servers, and the products on it share one set of things underneath: roles and policy, memory, model routing, budgets, and an audit trail. People and agents work in the same apps, so an agent that files a task, answers a ticket or rolls out a flag does it under the same permissions as a person, and the action lands in the same log. Where you run it decides where the data lives. See [Choose how to run Venom](/docs/getting-started/choose-how-to-run.md). ## Workspace apps {#workspace} The apps share one rail and one `⌘K` search (see [the workspace](/docs/cloud/workspace.md)). Each has its own MCP server, so an agent connects only the products it needs and its context holds only their tools. Every endpoint is `https://cloud.usevenom.dev/workspace/mcp/` on Venom Cloud, and the same path on your own deployment. The [MCP overview](/docs/cloud/workspace-mcp.md) covers sign-in and scopes. Every app here can also be built on: each has MCP tools, REST routes and webhook events, listed on its developer page in [Build with Venom](/docs/developers.md). Add-ons are products an organisation switches on. While an add-on has no price set on a deployment it is in preview: every organisation has it and there is nothing to buy. ### Notes (Venom Notes) {#notes} Shared markdown notes with `[[wikilinks]]`, databases, a graph, sharing and publishing. MCP: `/workspace/mcp/globe`. Add-on. [Docs](/docs/globe.md). ### Tasks {#tasks} Issues, projects, cycles and views for people and agents, with work delegated to an agent. MCP: `/workspace/mcp/tasks`. Add-on. [Docs](/docs/cloud/tasks.md). ### People and Funnel {#people} People is your own relationships: who someone is, how you met, when you last spoke. Funnel puts deals, pipelines and a forecast on top of it. MCP: `/workspace/mcp/people` and `/workspace/mcp/funnel`. Not add-ons. [People](/docs/cloud/people.md), [Funnel](/docs/cloud/funnel.md). ### Support {#support} A shared inbox for customer email and form requests, with notes and replies drafted from your notes. MCP: `/workspace/mcp/support`. Not an add-on. [Docs](/docs/cloud/support.md). ### Chat {#chat} Team chat where people and agents are both members: channels, direct messages, threads. MCP: `/workspace/mcp/chat`. Not an add-on. [Docs](/docs/cloud/chat.md). ### Forms {#forms} A form builder with logic, links to share, and responses sent where the team works. MCP: `/workspace/mcp/forms`. Add-on. [Docs](/docs/cloud/forms.md). ### Flags {#flags} Feature flags with environments, targeting and percentage rollouts, each change reviewed before it saves. MCP: `/workspace/mcp/flags`. Add-on. [Docs](/docs/cloud/flags.md). ### Experiments {#experiments} A/B tests on flags, with sequential results, sample ratio checks and guardrails. MCP: `/workspace/mcp/exp`. Add-on. [Docs](/docs/cloud/experiments.md). ### Incidents and Status pages {#incidents} Incidents is error tracking for your own apps, grouped by cause, with the flag and the release in hand, plus alerts and on-call. MCP: `/workspace/mcp/incidents`. Add-on. The Status page publishes uptime from your own checks, with maintenance windows and subscribers. MCP: `/workspace/mcp/status`. [Incidents](/docs/incidents.md), [Status page](/docs/cloud/status-page.md). ### Comms and Venom Line {#comms} Comms is one API for SMS, WhatsApp, RCS, Telegram and phone calls through your own provider account, with opt-outs and quiet hours. Venom Line is an AI voice agent that answers your number. MCP: `/workspace/mcp/comms`. Not an add-on. [Comms](/docs/comms.md), [Venom Line](/docs/comms/venom-line.md). ### Calendar {#calendar} Your calendars and booking pages: .ics feeds, schedules, event types, free times, booking links and bookings. MCP: `/workspace/mcp/calendar`. [Docs](/docs/calendar.md). ### Org and Admin {#org-admin} Org is the organisation's teams and subteams with their members and roles, shared by every product. Admin is the console's admin pages (members, keys, budgets, routing, webhooks, audit and more) as tools. MCP: `/workspace/mcp/org` and `/workspace/mcp/admin`. [Teams](/docs/cloud/teams.md), [Build on Admin and the mesh](/docs/developers/admin.md). ### Voice {#voice} Speak to venom and have it answer, through your own speech models or cloud ones, behind one OpenAI-shaped audio API. No MCP endpoint. [Docs](/docs/voice.md). ## Agents and builders {#agents} ### The venom CLI and its harness {#cli} The `venom` terminal coding agent, with a permission engine, an OS sandbox on macOS and Linux, subagents and plan mode. The harness is the same agent as a library (`@venom/harness`) for your own app. Free and MIT licensed. [CLI](/docs/cli.md), [harness](/docs/harness.md). ### venom serve {#serve} The harness sessions over HTTP and Server-Sent Events, so an app in any language can create sessions, stream events and answer approvals. [Docs](/docs/server-api.md). ### Editor and browser clients {#clients} - **VS Code**: a chat panel over `venom serve`, with approvals and per-hunk undo. [Docs](/docs/integrations/vscode.md). - **Zed and other ACP editors**: `venom acp` serves venom as an Agent Client Protocol agent on stdio. [Docs](/docs/integrations/acp-zed.md). - **Chrome and Edge**: `venom --chrome-extension` lets the agent use your own logged-in browser through an extension. [Docs](/docs/integrations/browser-extension.md). - **Claude Code**: a plugin that sends each finished session, redacted on your machine, to your own cloud. [Docs](/docs/cloud/claude-code-sessions.md). ## Infrastructure {#infrastructure} ### The orchestrator and gateway {#orchestrator} A self-hosted OpenAI-compatible gateway in Go in front of vLLM, SGLang, llama.cpp, Ollama and the cloud providers you allow, with fallback, session-sticky routing and usage kept in SQLite. [Docs](/docs/orchestrator.md). ### The desktop daemon and the mesh {#daemon} `venom-daemon` runs the orchestrator on a desktop or GPU box without Docker. In mesh mode it dials out to Venom Cloud, so your GPUs serve your team while provider keys stay on the machine. [Daemon](/docs/deploy/desktop-daemon.md), [Mesh](/docs/mesh.md). ## Plans {#plans} Billing is a flat fee per organisation plus metered usage, never per seat. See [Organisation settings](/docs/cloud/console-settings.md#billing) for the plans and what is metered. ================================================================================ # Build with Venom URL: https://cloud.usevenom.dev/docs/developers Description: Build on every Venom product from code or an agent. Each product has MCP tools and REST routes behind the same API keys and OAuth scopes, with webhooks for what changed. Start here for auth, conventions, a quick start and a page per product. Every workspace product in Venom Cloud (Notes, Tasks, People, Funnel, Calendar, Comms, Support, Chat, Incidents, the Status page, Forms, Flags, Experiments, Org, Computers and Admin) can be driven from your own code or an agent. There are two ways in, and they reach the same functions: - **MCP.** Each product is its own MCP server at `/workspace/mcp/`. Connect Claude Code, Cursor, ChatGPT or your own agent to the products it needs. - **REST.** Each MCP tool that a script needs has a route under `/api/v1`, described by an OpenAPI document. Flags, Forms, Incidents, Experiments and Comms also have APIs of their own for app runtimes (SDK keys, event ingest). A REST route calls the MCP tool of the same name with the same arguments, access checks and rate window. So what an agent may do and what a script may do cannot drift apart. Changes come back to you as signed webhooks. ## Quick start {#quickstart} You need your cloud's address and a Venom API key. Create the key in the console under Settings, API keys, and turn on "This key is mine" so it acts as you (see [Authentication and scopes](/docs/developers/auth.md)). ```bash export VENOM_CLOUD=https://cloud.usevenom.dev export VENOM_API_KEY=vck_… ``` ### curl {#curl} List the products, then create an issue and read it back: ```bash curl "$VENOM_CLOUD/api/v1/products" -H "Authorization: Bearer $VENOM_API_KEY" curl -X POST "$VENOM_CLOUD/api/v1/issues" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"team": "ENG", "title": "Fix the login timeout"}' curl "$VENOM_CLOUD/api/v1/issues/ENG-12" -H "Authorization: Bearer $VENOM_API_KEY" ``` The same tool over MCP is one JSON-RPC call: ```bash curl -X POST "$VENOM_CLOUD/workspace/mcp/tasks" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "tasks_issue_get", "arguments": {"id": "ENG-12"}}}' ``` ### TypeScript {#typescript} No SDK is needed: `fetch` and a bearer token. ```ts const base = `${process.env.VENOM_CLOUD}/api/v1`; const headers = { Authorization: `Bearer ${process.env.VENOM_API_KEY}`, "Content-Type": "application/json" }; async function venom(method: string, path: string, body?: unknown, extra: Record = {}) { const res = await fetch(`${base}${path}`, { method, headers: { ...headers, ...extra }, body: body === undefined ? undefined : JSON.stringify(body) }); const json = await res.json(); if (!res.ok) throw new Error(`${res.status} ${json.error?.code}: ${json.error?.message}`); return { data: json, version: res.headers.get("etag") }; } const created = await venom("POST", "/issues", { team: "ENG", title: "Fix the login timeout" }, { "Idempotency-Key": crypto.randomUUID() }); const { data, version } = await venom("GET", "/issues/ENG-12"); // Only write if nobody changed the issue since this read: a stale write is 412. await venom("PATCH", "/issues/ENG-12", { state: "In Review" }, version ? { "If-Match": version } : {}); ``` ### Python {#python} The standard library is enough. ```python import json, os, urllib.request, uuid BASE = os.environ["VENOM_CLOUD"] + "/api/v1" KEY = os.environ["VENOM_API_KEY"] def venom(method, path, body=None, headers=None): req = urllib.request.Request(BASE + path, method=method, data=None if body is None else json.dumps(body).encode(), headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json", **(headers or {})}) with urllib.request.urlopen(req) as res: # raises HTTPError on 4xx and 5xx; its body is {"error": {...}} return json.load(res), res.headers.get("ETag") venom("POST", "/issues", {"team": "ENG", "title": "Fix the login timeout"}, {"Idempotency-Key": str(uuid.uuid4())}) issue, version = venom("GET", "/issues/ENG-12") venom("PATCH", "/issues/ENG-12", {"state": "In Review"}, {"If-Match": version} if version else None) ``` ## Products {#products} Each product's page lists what you can build with it, its REST routes, its MCP tools, the scopes they need, a worked example and its webhook events. The counts below come from the code on every docs build. | Product | What it is for | MCP tools | REST routes | Events | Developer page | |---|---|---|---|---|---| | Notes | Notes: markdown notes with wikilinks, databases, vaults, sharing and publishing. | 92 | 94 | 6 | [Build on Notes](/docs/developers/globe) | | Tasks | Issues, projects, cycles, views and teams; delegate work to agents. | 221 | 228 | 5 | [Build on Tasks](/docs/developers/tasks) | | Flags | Feature flags, environments, targeting and rollouts. | 42 | 42 | 3 | [Build on Flags](/docs/developers/flags) | | Forms | Build, publish and read forms and their responses. | 19 | 23 | 1 | [Build on Forms](/docs/developers/forms) | | Incidents | Errors, incidents, alerts and on-call. | 56 | 111 | 7 | [Build on Incidents](/docs/developers/incidents) | | Experiments | Experiments, metrics and results, run through Flags. | 25 | 22 | 5 | [Build on Experiments](/docs/developers/experiments) | | People | Your own relationships: people, notes, circles, follow-ups and warm intros. | 135 | 136 | 3 | [Build on People](/docs/developers/people) | | Funnel | Deals, pipelines, forecast and reports; deals link your People. | 38 | 55 | 4 | [Build on Funnel](/docs/developers/funnel) | | Support | The shared support inbox: triage conversations, add notes, draft replies from your notes. | 26 | 27 | 2 | [Build on Support](/docs/developers/support) | | Chat | Team chat where people and agents are members: read channels, post, react and follow threads. | 32 | 32 | 3 | [Build on Chat](/docs/developers/chat) | | Status page | The public status page: uptime checks, maintenance windows, subscribers and incident updates. | 16 | 16 | 7 | [Build on Status page](/docs/developers/status) | | Comms | Messages and phone calls to people (SMS, WhatsApp, RCS, Telegram, voice). | 27 | 55 | 7 | [Build on Comms](/docs/developers/comms) | | Calendar | Your calendars and booking pages: .ics feeds, schedules, event types, free times, booking links and bookings. | 41 | 43 | 5 | [Build on Calendar](/docs/developers/calendar) | | Admin | Console admin: members, budgets, providers, keys, routing, guardrails, webhooks, daemons and the audit log. | 269 | 269 | 34 | [Build on Admin](/docs/developers/admin) | | Org | The organisation's teams and subteams, their members and roles, shared by every product. | 10 | 10 | 5 | [Build on Org](/docs/developers/org) | | Computers | Each agent's own persistent browser on your daemons: start, stop, watch activity, ask a person to take over. | 36 | 0 | 0 | [Build on Computers](/docs/developers/computers) | | Agents | Chats with coding agents on your daemons' projects and agents on your computers, run on your machines. | 48 | 48 | 0 | [Build on Agents](/docs/developers/agents) | | Studio | Decks, pages and HTML pages built from blocks and charts, versioned and shared by link. | 30 | 31 | 0 | [Build on Studio](/docs/developers/studio) | ## The building blocks {#blocks} | Page | What it covers | |---|---| | [Authentication and scopes](/docs/developers/auth.md) | API keys (`vck_`), OAuth for MCP clients (`vga_` tokens), scopes per product, service agents | | [The REST twin and OpenAPI](/docs/developers/rest.md) | `/api/v1`, the OpenAPI document, how a request maps to a tool, the product APIs | | [MCP servers](/docs/developers/mcp.md) | the endpoint per product, the combined endpoint, connecting clients | | [Errors, limits, idempotency and pagination](/docs/developers/conventions.md) | the error shape and statuses, rate limits, `Idempotency-Key`, `If-Match`, cursors | | [Webhooks and events](/docs/developers/webhooks.md) | org webhook endpoints, the signed envelope, retries, every event type | The inference API (`/v1/chat/completions` and the rest of the OpenAI-shaped surface) and the admin and mesh APIs are covered in [Build on Admin and the mesh](/docs/developers/admin.md) and the generated [Venom Cloud API](/docs/api/cloud) reference. ## In this section {#in-this-section} - [Authentication and scopes](/docs/developers/auth.md): Which credential to use for each Venom API. Personal and team API keys, OAuth 2.1 for MCP clients with its endpoints and token lifetimes, the scopes per product, service agents, and the keys that belong to app runtimes. - [The REST twin and OpenAPI](/docs/developers/rest.md): Call Venom's workspace products over plain HTTP at /api/v1. Each route runs the MCP tool of the same name, with the same keys, checks and limits, an OpenAPI 3.1 document, If-Match for safe writes and Idempotency-Key for retries. - [MCP servers](/docs/developers/mcp.md): Connect an agent to Venom over MCP. One connection at /workspace/mcp whose listed products you switch on, or one server per product at /workspace/mcp/, the connect commands for common clients, and how a raw JSON-RPC call looks. - [Errors, limits, idempotency and pagination](/docs/developers/conventions.md): How the workspace APIs answer errors, how many requests they take a minute, how to retry a create without making it twice, how to write only when nothing changed since your read, and how to page through lists. - [Webhooks and events](/docs/developers/webhooks.md): Get told when something happens in Venom. Add an org webhook endpoint, pick its events, verify the signature, handle retries, and see every event type each product sends. - [Build on Venom Notes](/docs/developers/globe.md): Read, write and search notes and databases from code or an agent. Write meeting notes, file suggestions for a person to review, query databases and follow org vault changes over REST or MCP. - [Build on Venom Tasks](/docs/developers/tasks.md): Create, find and update Tasks issues from code, and run agents that claim delegated work, report progress and hand it back, over REST or MCP. - [Build on Venom People](/docs/developers/people.md): Search, add and update the people a member knows, log interactions and draft follow-ups from code or an agent, over REST or MCP. People is personal, so every call acts for one member. - [Build on Venom Funnel and Outreach](/docs/developers/funnel.md): Work with deals, pipelines, products, goals, reports and Outreach sequences from code or an agent, over REST or MCP, as the member whose People the deals link. - [Build on Venom Calendar](/docs/developers/calendar.md): Work with a member's calendar from code or an agent. Find free times, book and move meetings, manage event types and schedules, send time offers and group polls over REST or MCP, and put booking pages on your own site. - [Build on Venom Comms](/docs/developers/comms.md): Send messages and place phone calls from your app or an agent. Text people on SMS, WhatsApp, RCS, Telegram or email, run fallback profiles, read conversations and follow replies over the Comms API or MCP. - [Build on Venom Support](/docs/developers/support.md): Read and triage the support inbox from code or an agent. Assign and tag conversations, add internal notes, draft replies from your notes and send them once a person approves, over REST or MCP. - [Build on Venom Chat](/docs/developers/chat.md): Read channels and DMs, post and reply in threads, react, search, and follow chat with a change cursor from code or an agent, over REST or MCP. A team key joins as an agent member. - [Build on Venom Incidents](/docs/developers/incidents.md): Triage errors, run incidents and manage on-call from code or an agent. Read and resolve error issues, declare and update incidents, page people and change alert rules over REST or MCP, and send errors from your apps with an SDK key. - [Build on the Status page](/docs/developers/status.md): Manage the public status page from code or an agent. Add uptime checks, read their results, schedule maintenance, edit the listed services and manage subscribers over REST or MCP. - [Build on Venom Forms](/docs/developers/forms.md): Build, preview, publish and close forms from code or an agent, read and export their responses, and send each response to Notes, Tasks, Slack, Funnel, Support, Calendar or your own webhook, over REST or MCP. - [Build on Venom Flags](/docs/developers/flags.md): Create, target, roll out, evaluate and revert feature flags from code or an agent, over the Flags REST API, the SDK endpoints or MCP, and receive every flag change as a signed webhook. - [Build on Venom Experiments](/docs/developers/experiments.md): Define metrics, propose, start, ramp, read and decide A/B tests and guarded rollouts on Venom Flags flags, run product analytics queries and send events, over the Experiments REST API, the event endpoint or MCP. - [Build on Org and teams](/docs/developers/org.md): Read and manage the organisation's teams, subteams and team members from code or an agent, over REST or MCP, with the same rules as Settings, Teams. - [Build on Computers](/docs/developers/computers.md): Give agents their own persistent browsers on your daemons from code or an agent. Create, start and stop computers, read what they did, ask a person to take over and manage a shared computer's agents over MCP. - [Build on Agents](/docs/developers/agents.md): Start and drive chats with coding agents on your daemons' projects and with agents on your computers, from code or another agent, over MCP or REST. - [Build on Admin and the mesh](/docs/developers/admin.md): Run the org's console admin pages from code or an agent (members, budgets, provider keys, routing, webhooks, alerts, audit, daemons and more) with your member role, and find the admin, client and daemon APIs. - [Build on Studio](/docs/developers/studio.md): Make decks, pages and HTML pages from code or an agent. Create them from blocks and charts, change one slide or block by id, keep versions, and share by link over MCP and REST. ================================================================================ # Authentication and scopes URL: https://cloud.usevenom.dev/docs/developers/auth Description: Which credential to use for each Venom API. Personal and team API keys, OAuth 2.1 for MCP clients with its endpoints and token lifetimes, the scopes per product, service agents, and the keys that belong to app runtimes. Every request carries one credential as `Authorization: Bearer `. The workspace APIs never read a cookie. | Credential | Looks like | Use it for | Made by | |---|---|---|---| | Personal API key | `vck_…` with "This key is mine" on | scripts and agents that act as you, on MCP and REST | you, in Settings, API keys | | Team API key | `vck_…` | shared services, CI, the venom CLI on `/v1` | a developer or admin, in Settings, API keys | | OAuth access token | `vga_…` | MCP clients that sign in through a browser (Claude Code, ChatGPT, Cursor) | the OAuth flow below | | SDK key and client id | `vfs_…`, `vfm_…`, `vfc_…` | your app's runtime calls to Flags, Experiments and Incidents | each Flags environment | | Admin key and admin token | `vak_…`, the deployment's admin token | the admin API under `/api/admin/v1` | the operator ([Build on Admin and the mesh](/docs/developers/admin.md)) | A key is shown once, when it is made. The cloud keeps only its hash and its first characters. ## API keys {#keys} A **personal key** belongs to a member. On the workspace APIs it acts as that member: their role is the ceiling, and writes are audited as that member through the agent. Use one for anything that should do what you could do in the app. A **team key** has no member. What it may do depends on the product, because some products are personal: | Product | A team key | |---|---| | People, Calendar, Admin | is refused: they need a member | | Status page | reads only | | Org and teams | reads teams that are not private; with a bound service agent, acts as that agent | | Tasks | reads; with a bound service agent, acts as that agent in the teams the admin picked | | Notes | reads the shared vaults; it cannot write notes and never sees a personal vault | | Support | works: the inbox is the org's | | Chat | acts as an agent member | | Flags, Experiments | reads and writes flags as the key (`flags:read` and `flags:write`) | | Comms | acts as an agent: reads, and sends only as the sending profile allows agents | Each product page has the exact rule under "Authentication and scopes". ### Service agents {#service-agents} An admin can bind a team key to a named **service agent** (Venom Tasks, Settings, Members and agents, Agent access). The agent then shows by name on everything it does, and the admin can narrow it: read only, which apps (Notes, Tasks), and which teams. The scope holds on `/workspace/mcp`, `/api/v1` and the per-app servers. Agents that act for a member (a personal key, a connected app) follow the member's role instead. See [Venom Tasks for agents](/docs/cloud/tasks-mcp.md). ### Naming agents on a shared key {#agent-header} Rate limits are per agent. Several daemons or sessions that share one key each get their own window when they send `x-venom-agent: `. The key keeps a ceiling over all of them (see [limits](/docs/developers/conventions.md#limits)). ## OAuth for MCP clients {#oauth} Clients that connect by URL run OAuth 2.1 against the cloud's one authorization server. You don't need to build any of this to use a client such as Claude Code; it is here for people writing their own client. | What | Where | |---|---| | Protected resource metadata (RFC 9728) | `/.well-known/oauth-protected-resource/workspace/mcp`, and `…/workspace/mcp/` for a product endpoint | | Authorization server metadata (RFC 8414) | `/.well-known/oauth-authorization-server` | | Dynamic client registration (RFC 7591) | `POST /globe/oauth/register` | | Authorization | `/globe/oauth/authorize` (a browser page: the member signs in and ticks the scopes) | | Token and refresh | `POST /globe/oauth/token` | | Revocation | `POST /globe/oauth/revoke` | - PKCE with `S256` is required. Redirect URIs are checked against the registration (at most 10). - The resource is the MCP endpoint, `https:///workspace/mcp`. A product endpoint such as `/workspace/mcp/tasks` is the same resource narrowed to one product, so one grant works on every endpoint it has scopes for, and on the REST twin under `/api/v1`. - Lifetimes: an authorization code 60 seconds, an access token (`vga_`) 1 hour, a refresh token (`vgr_`) 30 days. - A `401` from an MCP endpoint carries `WWW-Authenticate` pointing at the protected resource metadata, which is how clients discover all of the above. - A member sees and disconnects their connected apps in the console (Connect an agent, `/connect`). Disconnecting stops the app's tokens at once. ## Scopes {#scopes} Each product has a `:read` and a `:write` scope. Incidents also has `incidents:admin`. A tool needs its product's `:write` scope when it changes something and `:read` otherwise; the cross-product `workspace_*` tools ask each product they touch. The scope only narrows: the member's role still decides. | Endpoint the client connects to | Default grant when the client names no scope | |---|---| | `/workspace/mcp/` | that product's `:read` and `:write` (never `incidents:admin`) | | `/workspace/mcp` | `:read` and `:write` on every product except Admin; never `incidents:admin` | A client that sends `scope=` gets at most what it asks for. On a product endpoint, scopes of other products are dropped, and a request left with none is refused with `invalid_scope`. Admin scopes (`admin:read`, `admin:write` on the combined endpoint, and `incidents:admin` anywhere) are granted only when the client asks for them. On the consent screen read is always on; the member can untick write or admin. Funnel's tools also accept `people:read` and `people:write`, from before Funnel had its own scopes. A tool outside the grant is refused with words that name the missing scope and how to reconnect. The scopes, generated from the product registry: | Product | Endpoint | Server name | Tools | Scopes | |---|---|---|---|---| | [Notes](/docs/developers/globe) | `/workspace/mcp/globe` | `venom-globe` | 92 | `globe:read` `globe:write` | | [Tasks](/docs/developers/tasks) | `/workspace/mcp/tasks` | `venom-tasks` | 221 | `tasks:read` `tasks:write` | | [Flags](/docs/developers/flags) | `/workspace/mcp/flags` | `venom-flags` | 42 | `flags:read` `flags:write` | | [Forms](/docs/developers/forms) | `/workspace/mcp/forms` | `venom-forms` | 19 | `forms:read` `forms:write` | | [Incidents](/docs/developers/incidents) | `/workspace/mcp/incidents` | `venom-incidents` | 56 | `incidents:read` `incidents:write` `incidents:admin` | | [Experiments](/docs/developers/experiments) | `/workspace/mcp/exp` | `venom-experiments` | 25 | `experiments:read` `experiments:write` | | [People](/docs/developers/people) | `/workspace/mcp/people` | `venom-people` | 135 | `people:read` `people:write` | | [Funnel](/docs/developers/funnel) | `/workspace/mcp/funnel` | `venom-funnel` | 38 | `funnel:read` `funnel:write` | | [Support](/docs/developers/support) | `/workspace/mcp/support` | `venom-support` | 26 | `support:read` `support:write` | | [Chat](/docs/developers/chat) | `/workspace/mcp/chat` | `venom-chat` | 32 | `chat:read` `chat:write` | | [Status page](/docs/developers/status) | `/workspace/mcp/status` | `venom-status` | 16 | `status:read` `status:write` | | [Comms](/docs/developers/comms) | `/workspace/mcp/comms` | `venom-comms` | 27 | `comms:read` `comms:write` | | [Calendar](/docs/developers/calendar) | `/workspace/mcp/calendar` | `venom-calendar` | 41 | `calendar:read` `calendar:write` | | [Admin](/docs/developers/admin) | `/workspace/mcp/admin` | `venom-admin` | 269 | `admin:read` `admin:write` | | [Org](/docs/developers/org) | `/workspace/mcp/org` | `venom-org` | 10 | `org:read` `org:write` | | [Computers](/docs/developers/computers) | `/workspace/mcp/computers` | `venom-computers` | 36 | `computers:read` `computers:write` | | [Agents](/docs/developers/agents) | `/workspace/mcp/agents` | `venom-agents` | 48 | `agents:read` `agents:write` | | [Studio](/docs/developers/studio) | `/workspace/mcp/studio` | `venom-studio` | 30 | `studio:read` `studio:write` | | Cross-product | `/workspace/mcp` | `venom` | 16 listed (every tool callable by name) | every product's `:read` and `:write` | 1179 tools in all. Generated from the code on every docs build. ## Errors {#errors} | Status | When | |---|---| | `401` | no credential, an unknown, revoked or expired one, or an OAuth token issued for another resource | | `403` | the credential is valid but may not do this: a read-only role, a team key on a personal product, a missing add-on, a scope the grant lacks, another agent's claim | The message says which. See [Errors, limits, idempotency and pagination](/docs/developers/conventions.md). ## Related {#related} - [API keys and key rotation](/docs/cloud/console-api-keys.md): creating, limiting, rotating and revoking keys. - [Venom for agents](/docs/cloud/workspace-mcp.md#oauth): OAuth and scopes as the MCP server applies them. - [Venom Cloud APIs overview](/docs/cloud/api-overview.md#credentials): every credential type, including the admin and daemon ones. ================================================================================ # The REST twin and OpenAPI URL: https://cloud.usevenom.dev/docs/developers/rest Description: Call Venom's workspace products over plain HTTP at /api/v1. Each route runs the MCP tool of the same name, with the same keys, checks and limits, an OpenAPI 3.1 document, If-Match for safe writes and Idempotency-Key for retries. A script or an app that does not speak MCP gets the same operations over plain HTTP at `/api/v1`. Every route names one MCP tool. The request becomes that tool's arguments, the call goes through the same server the MCP endpoint uses, and the answer becomes JSON. So the two cannot differ: the same credentials, access and add-on checks, rate window, argument names, limits and refusals. Only the envelope is HTTP. ## The APIs {#apis} | API | Base path | Operations | Source | |---|---|---|---| | REST twin of the MCP tools | `/api/v1` | 1079 | `GET /api/v1/openapi.json` (served, no credential) | | [Flags API](/docs/developers/flags#rest) | `/flags/api/v1` | 42 | `services/nodejs-cloud/contracts/flags-openapi.yaml` | | [Forms API](/docs/developers/forms#rest) | `/forms/api/v1` | 23 | `services/nodejs-cloud/contracts/forms-openapi.yaml` | | [Incidents API](/docs/developers/incidents#rest) | `/incidents/api/v1` | 51 | `services/nodejs-cloud/contracts/incidents-openapi.yaml` | | [Experiments API](/docs/developers/experiments#rest) | `/experiments/sdk/events` | 22 | `services/nodejs-cloud/contracts/experiments-openapi.yaml` | | [Comms API](/docs/developers/comms#rest) | `/v1/comms` | 28 | `services/nodejs-cloud/contracts/comms-openapi.yaml` | | [Outreach API](/docs/developers/funnel#rest) | `/v1/outreach/sequences` | 13 | `services/nodejs-cloud/contracts/outreach-openapi.yaml` | The REST twin covers Notes, Tasks, People, Funnel (Outreach included), Calendar, Support, Chat, the Status page, Incidents (`/api/v1/incidents`), Comms (`/api/v1/comms`), Org, Admin and the cross-product tools. Flags, Forms and Experiments are reached over their own APIs, which also serve your app's runtime (SDK keys, event ingest); Incidents and Comms keep theirs too (`/incidents/api/v1`, `/v1/comms`). Each product's page lists its routes, generated from these sources: see [Build with Venom](/docs/developers.md#products). ## The OpenAPI document {#openapi} `GET /api/v1/openapi.json` serves the twin's OpenAPI 3.1 document, with no credential needed. It is generated from the route table and the tools' own input schemas, so a tool that gains an argument gains it there too. Each operation names its tool in `x-mcp-tool`. Load it into an OpenAPI client generator, Postman or an agent framework that reads OpenAPI. ```bash curl "$VENOM_CLOUD/api/v1/openapi.json" -o venom-workspace.json ``` ## How a request maps to a tool {#mapping} - **Arguments.** Query parameters (on `GET` and `DELETE`) and JSON body fields (on `POST`, `PATCH` and `PUT`) are the tool's arguments under the same snake_case names. A path parameter fills the argument of its name (`{id}`, `{person}`, `{deal}`). An argument the route does not take is refused with `400` and the list of those it does. - **Lists in a query.** An array argument in a query string is comma separated: `?fields=identifier,state`. - **Answers.** Where a tool has a JSON form, the route asks for it and answers the structured result. Other answers are `{ "text": "…", "id": "…" }` with the tool's words and, for a create, the id it made. A create answers `201`. - **Versions.** A read's version comes back as the `ETag` header; send it as `If-Match` and it becomes the tool's `expect_version` (`412` when stale). - **Retries.** `Idempotency-Key` becomes the tool's `idempotency_key`. - **Batches.** `POST /api/v1/batch` takes `calls` of MCP tool names and arguments (`globe_note_write`, `tasks_issue_create`) and answers each step's text. A later step can use an earlier one's id as `$1.id`. - **CORS.** The routes answer browser preflights and expose `ETag`, `Retry-After` and `WWW-Authenticate`, so a browser app with a token can call them. Errors, rate limits, idempotency and paging are on [Errors, limits, idempotency and pagination](/docs/developers/conventions.md). ## Authentication {#auth} `Authorization: Bearer `: a Venom API key (`vck_…`; a personal key acts as its member) or an OAuth access token issued for the workspace resource, the same ones `/workspace/mcp` takes. See [Authentication and scopes](/docs/developers/auth.md). ## Example {#example} ```bash # Find issues, then move one, but only if nobody changed it since the read curl "$VENOM_CLOUD/api/v1/issues?query=login&limit=5" -H "Authorization: Bearer $VENOM_API_KEY" curl -i "$VENOM_CLOUD/api/v1/issues/ENG-12" -H "Authorization: Bearer $VENOM_API_KEY" # note the ETag header curl -X PATCH "$VENOM_CLOUD/api/v1/issues/ENG-12" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'If-Match: "2026-11-07T10:00:00.000Z"' \ -d '{"state": "In Review"}' ``` ## Clients {#clients} Thin TypeScript and Python clients for the notes and issues routes live in the Venom source tree (`clients/workspace-ts`, `@venom/workspace-client`; `clients/workspace-py`, `venom-workspace`). They are not published to a package registry. For everything else, `fetch` or `urllib` and the OpenAPI document are enough: see the [quick start](/docs/developers.md#quickstart). - TypeScript: `new VenomWorkspace({ baseUrl, apiKey })`; `venom.issues.get("ENG-12")` answers `{ data, version }`; pass `{ ifMatch: version }` or `{ idempotencyKey }` to a write; a stale write throws a `VenomApiError` whose `conflict` is true. - Python: `VenomWorkspace(base_url, api_key)`; `venom.issues.get("ENG-12")` answers a `Reply` with `.data` and `.version`; `if_match=` and `idempotency_key=` on writes; `VenomApiError.conflict`. ## Related {#related} - [MCP servers](/docs/developers/mcp.md) - [Venom Cloud API](/docs/api/cloud): the inference and other `/v1` routes, generated from their handlers. ================================================================================ # MCP servers URL: https://cloud.usevenom.dev/docs/developers/mcp Description: Connect an agent to Venom over MCP. One connection at /workspace/mcp whose listed products you switch on, or one server per product at /workspace/mcp/, the connect commands for common clients, and how a raw JSON-RPC call looks. Connect once to `/workspace/mcp` and switch on the products whose tools you want listed, or connect a product's own server. Either way an agent loads only the tools it needs. All endpoints share one authorization server, one rate limit and one change feed, so one sign-in covers every product. ## Endpoints {#endpoints} | Product | Endpoint | Server name | Tools | Scopes | |---|---|---|---|---| | [Notes](/docs/developers/globe) | `/workspace/mcp/globe` | `venom-globe` | 92 | `globe:read` `globe:write` | | [Tasks](/docs/developers/tasks) | `/workspace/mcp/tasks` | `venom-tasks` | 221 | `tasks:read` `tasks:write` | | [Flags](/docs/developers/flags) | `/workspace/mcp/flags` | `venom-flags` | 42 | `flags:read` `flags:write` | | [Forms](/docs/developers/forms) | `/workspace/mcp/forms` | `venom-forms` | 19 | `forms:read` `forms:write` | | [Incidents](/docs/developers/incidents) | `/workspace/mcp/incidents` | `venom-incidents` | 56 | `incidents:read` `incidents:write` `incidents:admin` | | [Experiments](/docs/developers/experiments) | `/workspace/mcp/exp` | `venom-experiments` | 25 | `experiments:read` `experiments:write` | | [People](/docs/developers/people) | `/workspace/mcp/people` | `venom-people` | 135 | `people:read` `people:write` | | [Funnel](/docs/developers/funnel) | `/workspace/mcp/funnel` | `venom-funnel` | 38 | `funnel:read` `funnel:write` | | [Support](/docs/developers/support) | `/workspace/mcp/support` | `venom-support` | 26 | `support:read` `support:write` | | [Chat](/docs/developers/chat) | `/workspace/mcp/chat` | `venom-chat` | 32 | `chat:read` `chat:write` | | [Status page](/docs/developers/status) | `/workspace/mcp/status` | `venom-status` | 16 | `status:read` `status:write` | | [Comms](/docs/developers/comms) | `/workspace/mcp/comms` | `venom-comms` | 27 | `comms:read` `comms:write` | | [Calendar](/docs/developers/calendar) | `/workspace/mcp/calendar` | `venom-calendar` | 41 | `calendar:read` `calendar:write` | | [Admin](/docs/developers/admin) | `/workspace/mcp/admin` | `venom-admin` | 269 | `admin:read` `admin:write` | | [Org](/docs/developers/org) | `/workspace/mcp/org` | `venom-org` | 10 | `org:read` `org:write` | | [Computers](/docs/developers/computers) | `/workspace/mcp/computers` | `venom-computers` | 36 | `computers:read` `computers:write` | | [Agents](/docs/developers/agents) | `/workspace/mcp/agents` | `venom-agents` | 48 | `agents:read` `agents:write` | | [Studio](/docs/developers/studio) | `/workspace/mcp/studio` | `venom-studio` | 30 | `studio:read` `studio:write` | | Cross-product | `/workspace/mcp` | `venom` | 16 listed (every tool callable by name) | every product's `:read` and `:write` | 1179 tools in all. Generated from the code on every docs build. - The transport is Streamable HTTP: JSON-RPC over `POST`, and an event stream on `GET` for resources you subscribe to. The server speaks MCP protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`. - A self-hosted Venom Cloud serves the same paths on its own origin. - `experiments` works in place of `exp` in a path. ### The combined endpoint {#combined} `/workspace/mcp` lists the cross-product tools (`workspace_*`): search across notes and issues, a batch that runs many tool calls in one round trip, the change feed, the product list, the connected agents and the license. Over an OAuth connection it also lists the core set of each product its person switched on, on the console's Connect page or with `workspace_listing_set` ([switching products on](/docs/cloud/workspace-mcp#listing)); that connection's `initialize` declares `tools.listChanged` and its stream sends `notifications/tools/list_changed` when the switches change. A product's tool runs there when called by name whether it is listed or not, alone or in a batch, so older scripts keep working; the scopes alone decide what may be called. `?products=all` (or `?products=tasks,globe`) lists those tools too; an unknown product is a `400` naming the real ones. 16 tools: 12 read, 4 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `workspace_agent_list` | List connected agents | read | each product's | `GET /api/v1/agents` | | `workspace_batch_run` | Run several tools in one call | write (destructive) | each product's | `POST /api/v1/batch` | | `workspace_change_list` | What changed | read | each product's | `GET /api/v1/changes` | | `workspace_draft_list` | List drafts waiting for the member | read | each product's | `GET /api/v1/drafts` | | `workspace_item_get` | Open items by reference | read | each product's | `GET /api/v1/items` | | `workspace_item_link` | Link two items | write | each product's | `POST /api/v1/items/links` | | `workspace_item_search` | Search every kind of item | read | each product's | `GET /api/v1/search` | | `workspace_item_unlink` | Remove a link between two items | write (destructive) | each product's | `DELETE /api/v1/items/links` | | `workspace_license_get` | Read the license status | read | each product's | `GET /api/v1/license` | | `workspace_link_list` | Everything linked to an item | read | each product's | `GET /api/v1/items/links` | | `workspace_listing_get` | Read a connection's listing | read | each product's | `GET /api/v1/listing` | | `workspace_listing_set` | Switch products on for this connection | write | each product's | `PUT /api/v1/listing` | | `workspace_product_list` | List Venom's products | read | each product's | `GET /api/v1/products` | | `workspace_tool_get` | Read tools' schemas | read | each product's | `GET /api/v1/tools` | | `workspace_tool_search` | Find the tool for a task | read | each product's | `GET /api/v1/tools/search` | | `workspace_web_search` | Search the web (Venom Search) | read | each product's | `POST /api/v1/web/search` | On a product endpoint, `workspace_batch_run` is listed and held to that product's tools; a tool of another product is unknown there. ## Connect a client {#connect} Claude Code, signing in through the browser, one connection for every product: ```bash claude mcp add --transport http venom https://cloud.usevenom.dev/workspace/mcp ``` Then run `/mcp` to sign in, and switch on the products to list on the console's Connect page (`/connect`). For a connector limited to one product, connect its own endpoint instead: ```bash claude mcp add --transport http venom-tasks https://cloud.usevenom.dev/workspace/mcp/tasks claude mcp add --transport http venom-globe https://cloud.usevenom.dev/workspace/mcp/globe ``` Then run `/mcp` to sign in to each. With a personal API key instead, add `--header "Authorization: Bearer vck_…"`. Cursor, VS Code and other clients that read a JSON config: ```json { "mcpServers": { "venom-tasks": { "url": "https://cloud.usevenom.dev/workspace/mcp/tasks", "headers": { "Authorization": "Bearer vck_…" } }, "venom-globe": { "url": "https://cloud.usevenom.dev/workspace/mcp/globe", "headers": { "Authorization": "Bearer vck_…" } } } } ``` ChatGPT, Claude and other apps that connect by URL take the endpoint and run the OAuth sign-in. The console's **Connect an agent** page (`/connect`) writes these lines for you. See [Authentication and scopes](/docs/developers/auth.md#oauth). ## A raw call {#raw} Your own agent can call a tool without an MCP library. `tools/list` lists the endpoint's tools with their input schemas and annotations (`readOnlyHint`, `destructiveHint`); `tools/call` runs one: ```bash curl -X POST "$VENOM_CLOUD/workspace/mcp/globe" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "globe_note_search", "arguments": {"query": "launch plan", "limit": 5}}}' ``` A refusal is a normal result with `isError: true` and the reason as text. Every caller gets the same tool list in the same order, so a client's cached tool definitions stay valid; a call the credential may not make is refused in words. ## Naming {#naming} A tool is `__`, for example `tasks_issue_create`. The verbs are `list`, `get`, `search`, `create`, `update`, `delete`, `archive` and `restore`, plus a domain verb where those do not fit (`claim`, `toggle`, `publish`). Names stay under 40 characters because clients prefix them (Claude Code shows `mcp__venom-tasks__tasks_issue_create`). Older names still run; [Venom for agents](/docs/cloud/workspace-mcp.md#naming) lists them. ## More {#more} [Venom for agents](/docs/cloud/workspace-mcp.md) covers the rest of the MCP server in depth: anchored edits, batches and `$1.id` references, versions and idempotency keys, the change feed, resource subscriptions, presence, service agents, prompts and speed budgets. ================================================================================ # Errors, limits, idempotency and pagination URL: https://cloud.usevenom.dev/docs/developers/conventions Description: How the workspace APIs answer errors, how many requests they take a minute, how to retry a create without making it twice, how to write only when nothing changed since your read, and how to page through lists. These rules hold for the MCP servers under `/workspace/mcp` and the REST twin under `/api/v1`, because a REST route runs the MCP tool. The product APIs of Flags, Forms, Incidents, Experiments and Comms follow the same error shape with a few differences, noted below. The inference and admin APIs have their own page: [Venom Cloud APIs overview](/docs/cloud/api-overview.md#errors). ## Errors {#errors} A REST error is JSON with a status code: ```json { "error": { "message": "ENG-12 changed since you read it (now version …); nothing was written.", "type": "invalid_request_error", "code": "version_conflict", "param": null } } ``` Branch on the status and `code`; `message` is written for people and is the tool's own words. | Status | `code` | Means | |---|---|---| | 400 | `invalid_request` | a parameter or field is missing or wrong, or the route does not take it (the message lists what it takes); `If-Match` or `Idempotency-Key` on a route whose tool has no such argument | | 401 | `invalid_api_key` and others | no credential, or one that is not valid; `WWW-Authenticate` points at the OAuth metadata | | 403 | `forbidden` | the credential may not do this: a read-only role, a team key on a personal product, a missing add-on, a scope the grant lacks, another agent's claim | | 404 | `not_found` | no such route, or no such thing that you can see | | 405 | `method_not_allowed` | the path exists with another method | | 412 | `version_conflict` | the thing changed since the `If-Match` version you sent; nothing was written | | 413 | `payload_too_large` | a body over 2 MiB | | 422 | `tool_error` | the tool refused in words, for example an edit anchor that is no longer in the note | | 429 | `rate_limit_exceeded` | over the rate window; `Retry-After` says how many seconds to wait | | 501 | `not_implemented` | the route's tool is not on this deployment yet | Over MCP the same refusals come back as a tool result with `isError: true` and the message as text, so an agent reads why and can fix its call. A malformed JSON-RPC request gets a JSON-RPC error instead. The REST twin derives 404, 403 and 412 from the tool's words, and anything it cannot place is 422. The product APIs (Flags, Forms, Incidents, Experiments) answer a stale write with `409 version_conflict` instead of 412. ## Rate limits {#limits} | API | Limit | Counted per | |---|---|---| | MCP and the REST twin (every Venom MCP server) | 240 requests a minute | agent: a personal key's agent, each connected app, each service agent, each name sent in `x-venom-agent` | | MCP and the REST twin | 960 requests a minute | credential, over all its agents | | Flags, Forms and Incidents APIs | 600 requests a minute | credential | A `workspace_batch_run` (or `POST /api/v1/batch`) counts one request more for each write step in it. Past a limit the answer is `429` with `Retry-After`, and the message says which limit. Windows start on the UTC minute. The inference API's limits are the key's own `rpm` and `tpm` ([Venom Cloud APIs overview](/docs/cloud/api-overview.md#limits)). Retry a `429` after `Retry-After`, and a `502`, `503` or `504` with backoff. Do not retry `400`, `401`, `403`, `404` or `422` unchanged: they will fail the same way. ## Retries without duplicates: `Idempotency-Key` {#idempotency} A create that takes an idempotency key runs once per key. Send a unique value (a UUID) as the `Idempotency-Key` header over REST, or as the `idempotency_key` argument over MCP. - A retry with the same key within 24 hours returns the first answer and creates nothing. Over MCP the answer ends with a "Replayed" line. - A call that was refused, or that crashed, frees its key, so you can fix the call and retry with the same key. - While the first call is still running, a retry is refused; wait and try again. - Reusing a key for a different tool is refused. Keys belong to your credential and your organisation. - A route whose tool takes no key answers `400` when you send the header. 12 tools take `idempotency_key` (generated from the tools' input schemas): - Calendar: `calendar_booking_create` - Comms: `comms_call_place`, `comms_message_send` - Notes: `globe_database_create`, `globe_database_import`, `globe_note_write`, `globe_row_create`, `globe_suggestion_create` - Tasks: `tasks_comment_create`, `tasks_issue_create`, `tasks_issue_duplicate`, `tasks_issue_progress` The Flags, Forms, Experiments and Comms APIs take `Idempotency-Key` on their creates too, with the same 24 hours. The inference API's `Idempotency-Key` is different: it re-attaches to a running job. ## Safe writes: `ETag` and `If-Match` {#versions} A read of a note, an issue or a database answers its version as the `ETag` header (and as `version` in the body). Send it back as `If-Match` on a write, or as `expect_version` over MCP. If the thing changed since your read, nothing is written: `412` over REST, a refusal over MCP. Read it again and redo your change. 16 tools take `expect_version` (generated from the tools' input schemas): - Notes: `globe_database_delete`, `globe_database_update`, `globe_note_delete`, `globe_note_edit`, `globe_note_property_update`, `globe_note_write`, `globe_row_delete`, `globe_row_update`, `globe_version_restore`, `globe_view_create`, `globe_view_update` - Studio: `studio_artifact_update`, `studio_content_edit`, `studio_html_edit`, `studio_version_restore` - Tasks: `tasks_issue_update` Anchored edits (`edits` on `globe_note_edit` and `tasks_issue_update`) need no version most of the time: each anchor must still match exactly once, or nothing changes. ## Pagination {#pagination} Most lists page with a cursor, and new lists always do; each tool says which arguments it takes, and its REST route takes the same ones as query parameters. - **Cursor.** The answer carries a cursor (`next_cursor`, or a "Cursor:" or "More:" line in text). Pass it back as `cursor` to get the next page; `next_cursor` is null on the last page. A cursor a list did not give is refused in words. Every list tool pages this way, in every product except Computers (a list read in full gives 100 rows by default, at most 500; a long list such as messages or audit entries states its own default). A list that also takes `before`, `after` or `offset` still does, and `cursor` works on top of them. `workspace_change_list` works this way too, so keep its cursor to follow changes. - **Offset.** A few lists take `offset` and `limit`. - **Before.** Time-ordered lists such as a person's interactions or a check's results take `before` (the oldest item you have) and `limit`. - **Since.** `since` (an ISO time) returns only what changed after it, so a client that checks back re-reads nothing. - **Limit.** `limit` caps a page. Each tool states its default and maximum in its input schema. 226 tools take `cursor` (generated from the tools' input schemas): - Admin: `admin_alert_hit_list`, `admin_alert_list`, `admin_audit_list`, `admin_autoscale_list`, `admin_bot_list`, `admin_budget_list`, `admin_daemon_list`, `admin_daemon_share_list`, `admin_eval_list`, `admin_experiment_list`, `admin_failure_list`, `admin_filter_list`, `admin_gear_list`, `admin_grant_list`, `admin_guardrail_list`, `admin_handoff_list`, `admin_integration_list`, `admin_key_list`, `admin_library_list`, `admin_live_list`, `admin_mcp_catalog_list`, `admin_mcpserver_list`, `admin_member_list`, `admin_memory_list`, `admin_myguardrail_list`, `admin_onboarding_list`, `admin_pack_list`, `admin_pause_list`, `admin_prompttest_list`, `admin_provider_list`, `admin_share_list`, `admin_skill_list`, `admin_spendalert_list`, `admin_spendlimit_list`, `admin_sso_group_list`, `admin_team_list`, `admin_webhook_delivery_list`, `admin_webhook_list` - Agents: `agents_attachment_list`, `agents_bot_list`, `agents_bot_routine_list`, `agents_bot_run_event_list`, `agents_bot_run_list`, `agents_bot_summary_list`, `agents_chat_list`, `agents_gear_list`, `agents_project_list`, `agents_server_list`, `agents_skill_list`, `agents_workspace_list` - Calendar: `calendar_account_list`, `calendar_booking_list`, `calendar_calendar_list`, `calendar_event_type_list`, `calendar_feed_list`, `calendar_offer_list`, `calendar_poll_list`, `calendar_reminder_list`, `calendar_schedule_list` - Chat: `chat_bookmark_list`, `chat_change_list`, `chat_channel_list`, `chat_feed_list`, `chat_keyword_list`, `chat_member_list`, `chat_message_list`, `chat_unread_list` - Comms: `comms_call_list`, `comms_conversation_list`, `comms_message_list`, `comms_optout_list`, `comms_profile_list`, `comms_provider_list`, `comms_sender_list`, `comms_template_list` - Computers: `computers_approval_list`, `computers_daemon_list`, `computers_routine_list`, `computers_routine_run_list`, `computers_run_list`, `computers_tab_list` - Experiments: `exp_event_list`, `exp_experiment_list`, `exp_insight_list`, `exp_metric_list` - Flags: `flags_approval_list`, `flags_change_list`, `flags_coderef_list`, `flags_environment_list`, `flags_flag_history`, `flags_flag_list`, `flags_project_list`, `flags_segment_list`, `flags_webhook_list` - Forms: `forms_delivery_list`, `forms_feed_list`, `forms_form_list`, `forms_response_list` - Funnel: `funnel_deal_list`, `funnel_field_list`, `funnel_goal_list`, `funnel_outreach_enrollment_list`, `funnel_outreach_queue_list`, `funnel_outreach_sequence_list`, `funnel_pipeline_list`, `funnel_product_list` - Notes: `globe_automation_list`, `globe_comment_list`, `globe_dashboard_list`, `globe_database_list`, `globe_favorite_list`, `globe_import_job_list`, `globe_import_list`, `globe_note_list`, `globe_notification_list`, `globe_row_list`, `globe_share_list`, `globe_shared_list`, `globe_source_list`, `globe_suggestion_list`, `globe_synced_list`, `globe_team_list`, `globe_team_member_list`, `globe_template_list`, `globe_trash_list`, `globe_vault_list`, `globe_version_list` - Incidents: `incidents_alert_hit_list`, `incidents_alert_list`, `incidents_artifact_list`, `incidents_error_list`, `incidents_event_list`, `incidents_incident_list`, `incidents_oncall_member_list`, `incidents_oncall_policy_list`, `incidents_oncall_schedule_list`, `incidents_oncall_source_list`, `incidents_project_list`, `incidents_release_list`, `incidents_rule_list` - Org: `org_team_list` - People: `people_attachment_list`, `people_brief_list`, `people_circle_list`, `people_classifier_history`, `people_company_list`, `people_controversy_list`, `people_correction_list`, `people_downvote_list`, `people_event_list`, `people_followup_list`, `people_graph_get`, `people_image_list`, `people_interaction_list`, `people_intro_list`, `people_introask_list`, `people_link_list`, `people_meeting_list`, `people_meetingreview_list`, `people_outreach_list`, `people_overnight_list`, `people_proposal_list`, `people_relationship_list`, `people_suggestion_list`, `people_trip_list` - Status page: `status_check_list`, `status_component_list`, `status_maintenance_list`, `status_subscriber_list` - Studio: `studio_artifact_list`, `studio_share_list`, `studio_theme_list`, `studio_version_list` - Support: `support_conversation_list`, `support_help_article_list`, `support_macro_list`, `support_message_list`, `support_sla_policy_list` - Tasks: `tasks_activity_list`, `tasks_agent_list`, `tasks_attachment_list`, `tasks_comment_list`, `tasks_cycle_list`, `tasks_dependency_list`, `tasks_document_list`, `tasks_export_list`, `tasks_favorite_list`, `tasks_follow_list`, `tasks_import_job_list`, `tasks_initiative_list`, `tasks_initiative_update_list`, `tasks_issue_search`, `tasks_label_list`, `tasks_labelgroup_list`, `tasks_link_list`, `tasks_member_list`, `tasks_milestone_list`, `tasks_note_list`, `tasks_notification_list`, `tasks_project_list`, `tasks_projectdep_list`, `tasks_projectlink_list`, `tasks_projectrequest_list`, `tasks_projectupdate_list`, `tasks_pullrequest_list`, `tasks_pulse_digest_list`, `tasks_recurring_list`, `tasks_release_list`, `tasks_releasekey_list`, `tasks_releasepipeline_list`, `tasks_reminder_list`, `tasks_request_list`, `tasks_saved_insight_list`, `tasks_state_list`, `tasks_suggestion_list`, `tasks_team_list`, `tasks_teammember_list`, `tasks_template_list`, `tasks_triagerule_list`, `tasks_updatecomment_list`, `tasks_view_list` - Cross-product: `workspace_agent_list`, `workspace_change_list`, `workspace_draft_list`, `workspace_link_list`, `workspace_product_list` 7 tools take `offset` (generated from the tools' input schemas): - Funnel: `funnel_deal_list` - Notes: `globe_note_get`, `globe_row_list` - People: `people_person_search`, `people_reach_search` - Support: `support_conversation_list` - Tasks: `tasks_issue_get` 12 tools take `before` (generated from the tools' input schemas): - Admin: `admin_alert_hit_list`, `admin_audit_list`, `admin_webhook_delivery_list` - Chat: `chat_message_list` - Computers: `computers_activity_list` - Forms: `forms_delivery_list`, `forms_form_history` - Funnel: `funnel_deal_move` - People: `people_interaction_list` - Status page: `status_check_results` - Tasks: `tasks_pulse_get`, `tasks_releasechangelog_get` 10 tools take `since` (generated from the tools' input schemas): - Admin: `admin_audit_list` - Chat: `chat_message_search` - Flags: `flags_flag_history` - Notes: `globe_note_list` - Incidents: `incidents_incident_get` - People: `people_relationship_create` - Tasks: `tasks_flow_insight_get`, `tasks_insight_get`, `tasks_issue_search` - Cross-product: `workspace_change_list` ## JSON answers and fields {#json} Over REST, a tool that has a JSON form always answers JSON (the route sets `format: "json"` for you). Other answers are `{ "text": "…", "id": "…" }`: the tool's words and, for a create, the id it made. Over MCP, pass `format: "json"` to get `structuredContent`; the default is short markdown, which is cheaper in an agent's context. `fields` picks what each row of a list carries. 6 tools take `fields` (generated from the tools' input schemas): - Forms: `forms_response_list` - Notes: `globe_note_list` - Studio: `studio_artifact_get` - Tasks: `tasks_issue_list_mine`, `tasks_issue_search`, `tasks_template_apply` ## Sizes {#sizes} - A request body is at most 2 MiB (`413` past it). - `workspace_batch_run` runs 1 to 25 steps. - `workspace_item_search` waits up to 3 seconds for each product and answers with what it has. ## Related {#related} - [Authentication and scopes](/docs/developers/auth.md) - [The REST twin and OpenAPI](/docs/developers/rest.md) - [Venom for agents](/docs/cloud/workspace-mcp.md#safe-writes-and-small-reads): the same rules as the MCP server describes them. ================================================================================ # Webhooks and events URL: https://cloud.usevenom.dev/docs/developers/webhooks Description: Get told when something happens in Venom. Add an org webhook endpoint, pick its events, verify the signature, handle retries, and see every event type each product sends. Venom sends events to your HTTPS endpoint as signed JSON POSTs. An org has one set of endpoints for every product: each endpoint picks the event types it wants. Nothing is sent until an owner or admin adds an endpoint. ## Add an endpoint {#endpoint} In the console, Settings, Webhooks: add an https URL, pick its events, and copy the signing secret. The secret is shown once, when the endpoint is made or its secret rotated. An org has at most 10 endpoints. Reading the endpoints needs `audit:read`; changing them needs `org:manage`. From code: - The admin API, `POST /api/admin/v1/webhooks`, creates one with an admin key ([Admin API: webhooks](/docs/cloud/api-admin-observability.md#webhooks)). - The `admin_webhook_*` tools and their REST routes list, change, test and delete endpoints and retry deliveries ([Build on Admin and the mesh](/docs/developers/admin.md)). Creating an endpoint and rotating its secret are left to a person on purpose, because the secret is shown once. A new endpoint gets what happens after it is added; nothing older is sent. ## What a delivery looks like {#delivery} ```text POST /your/endpoint HTTP/1.1 content-type: application/json user-agent: venom-cloud-webhooks/1 venom-signature: t=1762675200,v1=5f2c… venom-event: tasks.issue.updated venom-event-id: 0193… venom-delivery: 0193… ``` ```json { "id": "0193…", "type": "tasks.issue.updated", "created_at": "2026-11-09T10:00:00.000Z", "org": { "id": "org_…" }, "data": { "identifier": "ENG-12", "title": "Ship the launch", "state": "In Review" }, "links": { "issue": "https://cloud.usevenom.dev/tasks/issue/ENG-12" } } ``` - `id` is the event's id: the same on every retry of it, so use it to drop duplicates. - `data` carries ids, names, numbers and states. It never carries a key, a secret, request content, an issue's description, a comment's text or a note's body. Personal notes and Tasks rows only their owner sees never leave. - `links` points at the thing in the console. ## Verify the signature {#signature} `venom-signature` is `t=,v1=." with the endpoint's secret>`. Check it over the raw body, before you parse it, and refuse a `t` more than 5 minutes from your clock. ```ts import { createHmac, timingSafeEqual } from "node:crypto"; export function verify(secret: string, header: string | null, rawBody: string, toleranceS = 300): boolean { if (!header) return false; const parts = header.split(",").map((p) => p.trim().split("=")); const t = Number(parts.find(([k]) => k === "t")?.[1]); if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceS) return false; const want = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")); return parts.some(([k, v]) => k === "v1" && v?.length === want.length && timingSafeEqual(Buffer.from(v), want)); } ``` ```python import hashlib, hmac, time def verify(secret: str, header: str | None, raw_body: bytes, tolerance_s: int = 300) -> bool: if not header: return False parts = [p.strip().split("=", 1) for p in header.split(",")] t = next((v for k, v in parts if k == "t"), None) if t is None or not t.isdigit() or abs(time.time() - int(t)) > tolerance_s: return False want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return any(k == "v1" and hmac.compare_digest(v, want) for k, v in parts) ``` ## Retries {#retries} Answer with any 2xx within 5 seconds. Only the first 4 KiB of your answer is read. Anything else is a failure, and the delivery is tried again after 1, 2, 4, … up to 128 minutes (with ±20 % jitter), 9 attempts in all, about four hours; then it is marked failed. The delivery log in Settings, Webhooks shows each attempt, with **Retry** (a fresh set of attempts) and **Send test** (one `webhook.test` event, never retried). Events and deliveries are kept 30 days. In production the URL must be public https. The cloud checks every address the name resolves to when it connects, refuses private, loopback and metadata addresses, and does not follow redirects. ## How events are made {#batching} - Tasks and Notes events come from each product's change log, read once a minute. Several changes to one issue or note within that minute arrive as one event with the thing as it is now, so live typing in a note is one `globe.note.updated` a minute. - Spend, key and daemon events are sent once per thing and window (once a month per cap, once per budget and window), so a receiver is not flooded. ## Every event type {#events} 97 event types, generated from `lib/webhooks/events.ts`. | Event | Product | When | |---|---|---| | `spend_cap.warning` | [Admin and mesh](/docs/developers/admin) | The org's month-to-date spend reached 80 % of its monthly cap (once a month per cap). | | `spend_cap.reached` | [Admin and mesh](/docs/developers/admin) | The monthly cap is reached and requests are refused with 429 spend_cap_reached. | | `budget.warning` | [Admin and mesh](/docs/developers/admin) | A member, key, team or gear budget reached its warning share of the limit (once per budget and window). | | `budget.reached` | [Admin and mesh](/docs/developers/admin) | A budget is at its limit: requests are refused with 429 spend_limit_reached, or sent to its cheaper model (once per budget and window). | | `spend.threshold` | [Admin and mesh](/docs/developers/admin) | A budget's or the monthly cap's spend passed one of the org's alert thresholds (50, 80, 100 % by default; once per threshold and window). | | `spend.forecast` | [Admin and mesh](/docs/developers/admin) | At the current rate a budget or the monthly cap runs out before its window ends (once per window and limit). | | `spend.anomaly` | [Admin and mesh](/docs/developers/admin) | A key, member, model or gear spent far above its usual for the hour (robust hourly baseline, the org's floor and sensitivity), with the top requests and keys and a link to pause the key. | | `key.expiring` | [Admin and mesh](/docs/developers/admin) | An API key expires within 7 days (once per key and expiry). | | `key.expired` | [Admin and mesh](/docs/developers/admin) | An API key passed its expiry and no longer works. | | `daemon.offline` | [Admin and mesh](/docs/developers/admin) | A daemon stopped heartbeating: its lease lapsed more than 2 minutes ago. | | `daemon.online` | [Admin and mesh](/docs/developers/admin) | A daemon reported offline is heartbeating again. | | `autoscale.machine_added` | [Admin and mesh](/docs/developers/admin) | A pool asked its GPU cloud for a machine (demand, its floor or schedule, or Scale to N). | | `autoscale.machine_joined` | [Admin and mesh](/docs/developers/admin) | A pool's machine booted and its daemon joined the org. | | `autoscale.machine_draining` | [Admin and mesh](/docs/developers/admin) | A pool's machine stopped taking new requests before it is removed (idle, or scaled down). | | `autoscale.machine_removed` | [Admin and mesh](/docs/developers/admin) | A pool's machine was terminated at its GPU cloud, or vanished there. | | `autoscale.join_timeout` | [Admin and mesh](/docs/developers/admin) | A pool's machine did not join in time and was terminated; check the image and boot log. | | `autoscale.machine_interrupted` | [Admin and mesh](/docs/developers/admin) | A GPU cloud reclaimed a pool's spot or preemptible machine; its jobs were requeued and a replacement launched elsewhere. | | `autoscale.cap_reached` | [Admin and mesh](/docs/developers/admin) | A pool's estimated GPU spend reached its monthly cap; it adds no machines until next month. | | `prompt_filter.blocked` | [Admin and mesh](/docs/developers/admin) | A prompt filter refused a request (at most once per rule and key every 10 minutes). | | `quality.degraded` | [Admin and mesh](/docs/developers/admin) | Scheduled quality checks found a significant drop in a model's score or a rise in its latency on a suite. | | `quality.recovered` | [Admin and mesh](/docs/developers/admin) | A model flagged degraded is back near its baseline on that suite. | | `prompt_filter.response_blocked` | [Admin and mesh](/docs/developers/admin) | A response filter stopped a model's answer mid-way (at most once per rule and key every 10 minutes). | | `chargeback.statement` | [Admin and mesh](/docs/developers/admin) | Last month's spend per team, project, gear, key or member, sent on the 1st (UTC) when the monthly statement is on (Usage, Chargeback). | | `handoff.created` | [Admin and mesh](/docs/developers/admin) | A member handed a venom session to a teammate or a team (/handoff): who, to whom, the repository and branch; never the note. | | `handoff.accepted` | [Admin and mesh](/docs/developers/admin) | The recipient of a handoff accepted it (venom handoff accept) and took the session over. | | `handoff.declined` | [Admin and mesh](/docs/developers/admin) | The recipient of a handoff declined it. | | `key_rotation.due` | [Admin and mesh](/docs/developers/admin) | A provider key or API key reaches its rotation date within 14 days (the org's schedule or the key's own; once per key version). Names and last four characters only. | | `key_rotation.overdue` | [Admin and mesh](/docs/developers/admin) | A provider key or API key is past its rotation date (once per key version). | | `key_rotation.completed` | [Admin and mesh](/docs/developers/admin) | A rotated provider key's old key stopped serving after its grace period (or an admin retired it). Revoke it at the provider. | | `model.retiring` | [Admin and mesh](/docs/developers/admin) | A model the org's gears, routing rows or allow lists use retires within the org's warning window (30 days by default) or is gone from its provider's list (once per model and date). | | `price.changed` | [Admin and mesh](/docs/developers/admin) | The effective price of a model used in the last 30 days changed (a price table update, a custom price, a catalog sync): old and new price and the monthly impact at the last 30 days' use. | | `credits.expiring` | [Admin and mesh](/docs/developers/admin) | Prepaid credits or a free quota on a provider key expire within 7 days with a balance left (once per credit and expiry). Key name and amounts only. | | `sla.breach` | [Admin and mesh](/docs/developers/admin) | A customer's or route's service-level target (availability, p95 time to first token, error rate) is missed this month so far (once per target and month): the figures, the target and a link to the SLA page. | | `sla.credit_drafted` | [Admin and mesh](/docs/developers/admin) | A finished month breached a customer's SLA and a service credit was drafted for its next invoice; an admin approves it first (once per target and month). | | `tasks.issue.created` | [Tasks](/docs/developers/tasks) | A Venom Tasks issue was created, by a person or an agent: identifier, title, team, state, priority, assignee and delegate. Never the description. | | `tasks.issue.updated` | [Tasks](/docs/developers/tasks) | A Venom Tasks issue changed: its state, assignee, delegate (and whether an agent holds a claim on it), priority, labels or text. Several changes within a minute arrive as one event with the issue as it is now. | | `tasks.issue.deleted` | [Tasks](/docs/developers/tasks) | A Venom Tasks issue was deleted: its id and identifier. | | `tasks.comment.created` | [Tasks](/docs/developers/tasks) | A comment was added to a Venom Tasks issue, by a person or an agent's progress report: the issue, the comment id and who wrote it. Never the comment's text. | | `globe.note.created` | [Notes](/docs/developers/globe) | A note was created in the org vault of Venom Notes (never a personal vault's): its id, path and who wrote it. Never the note's text. | | `globe.note.updated` | [Notes](/docs/developers/globe) | A note in the org vault changed (its text, path or properties). Edits within a minute, live typing included, arrive as one event. | | `globe.note.deleted` | [Notes](/docs/developers/globe) | A note in the org vault was moved to the trash or deleted. | | `experiments.guardrail_breached` | [Experiments](/docs/developers/experiments) | A guardrail metric of a running experiment is worse than its tolerated regression (once per experiment and metric). | | `experiments.decided` | [Experiments](/docs/developers/experiments) | An experiment was decided: a variation shipped, a rollback or an iteration, by a person, an agent or the automatic guardrail rollback. | | `errors.issue.created` | [Incidents](/docs/developers/incidents) | A new error issue appeared in Venom Incidents (id, project, title, count and release; never the event itself). | | `errors.issue.regressed` | [Incidents](/docs/developers/incidents) | A resolved error issue happened again in Venom Incidents. | | `errors.alert.fired` | [Incidents](/docs/developers/incidents) | One of the org's error alert rules fired (rule, kind, issue, the numbers behind it, and the action). | | `incidents.created` | [Incidents](/docs/developers/incidents) | An incident was declared in Venom Incidents (number, title, severity, status, projects; never its notes). | | `incidents.updated` | [Incidents](/docs/developers/incidents) | An incident's status, severity, roles or title changed. | | `incidents.resolved` | [Incidents](/docs/developers/incidents) | An incident was resolved. | | `forms.response.created` | [Forms](/docs/developers/forms) | A response was submitted to a published Venom Forms form: its id, the form and the time. The answers are included only when the form's "include answers" setting is on (they can be personal data). | | `incidents.page` | [Incidents](/docs/developers/incidents) | Someone is being paged: the page, its title, the escalation level and the members told (so an org can bridge SMS or voice through its own gateway). Sent again at each escalation. | | `comms.message.received` | [Comms](/docs/developers/comms) | Someone wrote to one of the org's numbers (Venom Comms): the channel, the sender, the conversation and the text, plus what it asked for (ack, escalate, STOP). | | `support.conversation.created` | [Support](/docs/developers/support) | A conversation was opened in Venom Support (email, a form, a messaging channel or by hand): its id, number, subject, channel and priority. Never the customer's message. | | `support.sla.breached` | [Support](/docs/developers/support) | An open Support conversation ran past its first-reply or resolution time: its id, number, which SLA (first_response or resolution), the due time and the priority. Never the customer's message. | | `comms.message.status` | [Comms](/docs/developers/comms) | A message sent through Venom Comms changed status (sent, delivered, read, failed), with the provider's reason on a failure. | | `comms.call.answered` | [Comms](/docs/developers/comms) | A call placed through Venom Comms was answered. | | `comms.call.gather` | [Comms](/docs/developers/comms) | The person on a Venom Comms call pressed keys at a gather step: the step's name and the digits. | | `comms.call.ended` | [Comms](/docs/developers/comms) | A Venom Comms call ended: its result, duration and cost. | | `comms.call.status` | [Comms](/docs/developers/comms) | A Venom Comms call changed status (ringing, failed, busy, no answer). | | `comms.dispatch.acknowledged` | [Comms](/docs/developers/comms) | Someone acknowledged a Venom Comms profile run (a reply of 1 or ack, or key 1 on the call): no further steps go out. | | `calendar.booking.created` | [Calendar](/docs/developers/calendar) | Someone booked a time on a Venom Calendar booking page (or the owner booked for them): the booking, event type, time, status (confirmed, or pending when it needs your confirmation), and the invitee's name, email and time zone. Never their answers. | | `calendar.booking.confirmed` | [Calendar](/docs/developers/calendar) | The owner confirmed a pending booking. | | `calendar.booking.rescheduled` | [Calendar](/docs/developers/calendar) | A booking moved to a new time, by the invitee from their link or by the owner: the new time, the previous one and the invite's sequence. | | `calendar.booking.cancelled` | [Calendar](/docs/developers/calendar) | A booking was cancelled by the invitee or the owner, or a pending one was declined: the reason given, if any. | | `calendar.booking.no_show` | [Calendar](/docs/developers/calendar) | The owner marked a booking as a no-show after its start: the booking, its time and the invitee (Funnel can move the deal back). | | `tasks.issue.delegated` | [Tasks](/docs/developers/tasks) | A Venom Tasks issue was delegated to an agent (at creation or later, each new delegate): the issue, its identifier and title, the delegate agent's id, the previous delegate and who delegated it, so an agent learns of new work without holding a stream open. Never the description. | | `globe.team_note.created` | [Notes](/docs/developers/globe) | A note was created in a team vault of Venom Notes: its id, path, the ids of the teams whose vault holds it and who wrote it. Never the note's text, and never a personal vault's note. | | `globe.team_note.updated` | [Notes](/docs/developers/globe) | A note in a team vault changed (its text, path or properties): id, path, team ids and who. Edits within a minute arrive as one event. | | `globe.team_note.deleted` | [Notes](/docs/developers/globe) | A note in a team vault was moved to the trash or deleted: its id, path and team ids. | | `experiments.started` | [Experiments](/docs/developers/experiments) | An experiment started serving its treatments (by a person, an agent, or an approved request): the experiment, flag, environment, the treatments' share and who started it. | | `experiments.ramped` | [Experiments](/docs/developers/experiments) | A running experiment's treatment share changed (by hand, or a guarded rollout's next step): the share before and after, and who. | | `experiments.stopped` | [Experiments](/docs/developers/experiments) | A running experiment was stopped and control is served to everyone: the experiment, flag, environment and who stopped it. | | `people.person.created` | [People](/docs/developers/people) | A person became visible to the whole org in Venom People (added as org-wide, or shared with the org): id, name, role, company and the member who owns the record. Never handles, notes, how you met or interactions; a private or team-only person is never sent. | | `people.person.updated` | [People](/docs/developers/people) | An org-wide person in Venom People changed: the same short fields as when it was added. | | `people.person.removed` | [People](/docs/developers/people) | An org-wide person is no longer visible to the org: archived, merged into another, or made private or team-only again. Its id only. | | `funnel.deal.created` | [Funnel](/docs/developers/funnel) | A deal visible to the whole org was created in Venom Funnel: id, title, value, currency, pipeline, stage, status, owner and company. Never its notes or the people on it; a team-only deal is never sent. | | `funnel.deal.updated` | [Funnel](/docs/developers/funnel) | An org-wide deal's own fields changed (title, value, owner, company, expected close), or a team deal was opened to the org: the deal as it is now. A deal moved from the org to a team sends its id and visibility only. | | `funnel.deal.stage_changed` | [Funnel](/docs/developers/funnel) | An org-wide deal moved to another stage: the stage before and after, its status (open, won or lost) as it is now, and who moved it. | | `funnel.deal.archived` | [Funnel](/docs/developers/funnel) | An org-wide deal was archived: its id and title. | | `chat.channel.created` | [Chat](/docs/developers/chat) | A public channel was created in Venom Chat: id, name and who created it. Private channels and direct messages are never sent. | | `chat.channel.archived` | [Chat](/docs/developers/chat) | A public channel was archived in Venom Chat (or restored: `archived` false): id, name and who. | | `chat.message.created` | [Chat](/docs/developers/chat) | A message was posted in a public channel of Venom Chat, by a person, an agent or a feed: the message id, channel, thread, author and how it was posted. Never the text; private channels and direct messages are never sent. Busy: one event per message. | | `flags.flag.created` | [Flags](/docs/developers/flags) | A feature flag was created in Venom Flags: project, key, name, kind, version, who, and the audit entry. | | `flags.flag.updated` | [Flags](/docs/developers/flags) | A feature flag changed (turned on or off, targeting, rollout, variations, archived, or reverted): project, key, version, the environment, whether it is on in each environment, the paths that changed (never their values, which can name users) and who. | | `flags.flag.deleted` | [Flags](/docs/developers/flags) | A feature flag was deleted: project, key and who. | | `org.team.created` | [Org](/docs/developers/org) | A team was created in the organisation (shared by Tasks, Chat, Notes and People): id, key, name, parent, whether it is private, and who. | | `org.team.updated` | [Org](/docs/developers/org) | A team's name, key, parent, privacy or description changed: the team as it is now, and who. | | `org.team.archived` | [Org](/docs/developers/org) | A team was archived (or restored: `archived` false), and who did it. | | `org.team.member_added` | [Org](/docs/developers/org) | A person or agent joined a team: the team, the member's id, their role in it, and who added them. | | `org.team.member_removed` | [Org](/docs/developers/org) | A person or agent left a team: the team, the member's id and who removed them. | | `status.incident.created` | [Status page](/docs/developers/status) | An incident was published on the org's public status page: its title, impact, status, components and first update, as visitors see them. | | `status.incident.updated` | [Status page](/docs/developers/status) | A published status page incident got an update: its status and the update as posted on the page. | | `status.incident.resolved` | [Status page](/docs/developers/status) | A published status page incident was resolved. | | `status.maintenance.scheduled` | [Status page](/docs/developers/status) | A maintenance window was published on the status page: its title, times and components. | | `status.maintenance.started` | [Status page](/docs/developers/status) | A published maintenance window began. | | `status.maintenance.completed` | [Status page](/docs/developers/status) | A published maintenance window ended. | | `status.component.changed` | [Status page](/docs/developers/status) | A status page component (a model) went down or degraded, or is working again, as its automatic incidents see it: the component, its label, the new status (down, degraded, operational, or idle when it had no traffic) and the incident. | ## Other ways to follow changes {#other} - **The change feed.** `workspace_change_list` (`GET /api/v1/changes`) answers what changed in notes and issues since your cursor. Pull it on your own schedule; no endpoint needed. - **MCP resource subscriptions.** A connected MCP client can subscribe to a note or an issue and be told as it changes ([Venom for agents](/docs/cloud/workspace-mcp.md#subscriptions-and-the-stream)). - **Product webhooks.** Flags has webhooks of its own for flag changes, Forms sends each response to its destinations, and the Status page sends incident and maintenance updates to its readers' webhooks. Each product's page says what it has under "Events". - **Incoming webhooks.** Slack, Linear, Jira and Stripe call Venom: see [Incoming webhooks](/docs/cloud/api-webhooks.md). ## Related {#related} - [Organisation settings: webhooks](/docs/cloud/console-settings.md#webhooks) - [Admin API: logs, audit and alerts](/docs/cloud/api-admin-observability.md#webhooks) ================================================================================ # Build on Venom Notes URL: https://cloud.usevenom.dev/docs/developers/globe Description: Read, write and search notes and databases from code or an agent. Write meeting notes, file suggestions for a person to review, query databases and follow org vault changes over REST or MCP. Venom Notes holds your organisation's markdown notes and databases in vaults: each member's personal vault, the org vault and team vaults. Every Notes tool is an MCP tool on the workspace server and a REST route under `/api/v1`, and both run the same code as the Notes app, so the app's access rules, audit log and secret check apply. ## What you can build {#build} - **Meeting notes from a recorder.** Write a note after each call (`POST /api/v1/notes`, mode `create`), then add action items to it later with anchored edits (`PATCH /api/v1/notes/{id}`). - **A review queue instead of direct writes.** File new notes, appended text or links as suggestions in a vault's Inbox (`POST /api/v1/notes/suggestions`); a person applies or rejects each one in the app. - **Answers grounded in your notes.** Fetch the notes that answer a question as numbered citations (`POST /api/v1/notes/ask`) and let your own model write the answer. - **A tracker kept in a database.** Create a database with its columns (`POST /api/v1/databases`), add rows from a script (`POST /api/v1/databases/{database}/rows`) and read them back filtered (`GET /api/v1/databases/{database}/rows`). - **Sync into another tool.** Poll what changed in notes and issues with `GET /api/v1/changes` (the `workspace_change_list` tool), or receive the `globe.note.*` org webhooks below. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/globe`, server name `venom-globe` | | Connect | `claude mcp add --transport http venom-globe https://cloud.usevenom.dev/workspace/mcp/globe` | | MCP tools | 92 (37 read, 55 write) | | OAuth scopes | `globe:read` `globe:write` | | REST twin | 94 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `globe.note.created`, `globe.note.updated`, `globe.note.deleted`, `globe.team_note.created`, `globe.team_note.updated`, `globe.team_note.deleted` | ## Authentication and scopes {#scopes} What a caller sees depends on whether it acts for a member: - A **personal API key** acts for its member. It reads their personal vault, the org vault and the team vaults they belong to, and writes where their role may write. Every member writes their personal vault and their team vaults; writing the org vault needs the `org:manage` permission (owners and admins). - A **team key** has no member. It reads the org vault only, has no personal vault (`vault: "me"` is refused) and cannot write notes there, but it can file suggestions in the org vault's Inbox. If an admin bound it to a service agent, the agent's scope applies too: an agent scoped to other apps is refused every Notes tool, and a read-only agent cannot write or suggest. - An **OAuth app** acts for the member who connected it, with their rights. It needs `globe:read` to use Notes at all and `globe:write` to write, edit or suggest. Notes is included in the Team plan and up. An organisation without it gets a tool error that says so and links to the billing page; over REST that is `403 forbidden` with the same words. A self-hosted install without billing has Notes. A note in another member's personal vault, or in a team vault you are not in, answers as if it did not exist. ## Worked example {#example} Write a meeting note in your personal vault, then add an action item under its heading: ```bash curl -X POST "$VENOM_CLOUD/api/v1/notes" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Idempotency-Key: standup-2026-11-09' \ -d '{"vault": "me", "path": "Meetings/2026-11-09 Standup", "mode": "create", "body": "---\ntags: [standup]\n---\n## Notes\n\nShipped the importer.\n\n## Action items\n"}' curl -X PATCH "$VENOM_CLOUD/api/v1/notes/" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"edits": [{"op": "insert_after", "anchor": "## Action items\n", "text": "- [ ] Ana: review the importer PR\n"}]}' ``` The same edit over MCP, from any client connected to `/workspace/mcp/globe`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "globe_note_edit", "arguments": { "id": "", "edits": [{ "op": "insert_after", "anchor": "## Action items\n", "text": "- [ ] Ana: review the importer PR\n" }] } } } ``` Each anchor must match the note's current text exactly once, and the edits apply all or none. A read answers the note's version as its `ETag`; send it back as `If-Match` and a write that would overwrite someone else's change answers `412`. A retry with the same `Idempotency-Key` within 24 hours replays the first answer. If the credential cannot write the vault, file the same change as a suggestion instead: ```bash curl -X POST "$VENOM_CLOUD/api/v1/notes/suggestions" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"vault": "org", "suggestions": [{"kind": "append", "noteId": "", "heading": "Action items", "text": "- [ ] Ana: review the importer PR"}]}' ``` Suggestions go to the Inbox of your personal vault or the org vault; team vaults have no Inbox yet. ## Limits {#limits} - A note body is at most 200 KB and a request at most 1 MiB. - A write that contains a credential (an API key, a token, a private key) is refused and nothing is stored. - Every write is recorded in the organisation's audit log under the credential, with ids and content hashes, never the text. A note's history names the agent: "Claude Code (via MCP, for ana@example.com)". - Rate limits are those of the workspace server: see [Errors, limits and pagination](/docs/developers/conventions.md). ## The MCP endpoint of Notes alone {#globe-mcp} `POST /globe/mcp` still serves the same Notes tools as its own server, with its own limit of 120 requests a minute per credential. OAuth tokens issued for it work there only. New integrations should use `/workspace/mcp/globe`, which shares one credential and one rate window with the other products. Setup for both is in [Use Notes from any agent](/docs/integrations/globe-mcp.md). The Notes app's own HTTP API, `/globe/api/*`, uses the console's sign-in and is not for keys, with one exception: `/globe/api/sync`, which `venom globe sync` calls with a bearer key ([Sync a folder](/docs/globe/sync.md)). ## Events {#events} 6 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `globe.note.created` | A note was created in the org vault of Venom Notes (never a personal vault's): its id, path and who wrote it. Never the note's text. | | `globe.note.updated` | A note in the org vault changed (its text, path or properties). Edits within a minute, live typing included, arrive as one event. | | `globe.note.deleted` | A note in the org vault was moved to the trash or deleted. | | `globe.team_note.created` | A note was created in a team vault of Venom Notes: its id, path, the ids of the teams whose vault holds it and who wrote it. Never the note's text, and never a personal vault's note. | | `globe.team_note.updated` | A note in a team vault changed (its text, path or properties): id, path, team ids and who. Edits within a minute arrive as one event. | | `globe.team_note.deleted` | A note in a team vault was moved to the trash or deleted: its id, path and team ids. | Only notes in the org vault send events; personal and team vault notes never do. Edits to one note within a minute, live typing included, arrive as one `globe.note.updated`. For everything else, including personal notes your key can read, poll `GET /api/v1/changes` with the cursor from the previous answer. ## REST routes {#rest} The REST twin: 94 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/vaults** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/vaults` | List the vaults you can read | `globe_vault_list` | **/notes** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/notes` | List notes in a vault or folder, newest change first | `globe_note_list` | | POST | `/api/v1/notes` | Create a note, or append to or replace one | `globe_note_write` | | GET | `/api/v1/notes/search` | Search notes | `globe_note_search` | | POST | `/api/v1/notes/suggestions` | Put suggested notes in a vault's inbox for a person to review | `globe_suggestion_create` | | POST | `/api/v1/notes/ask` | Ask a question and get an answer from the notes | `globe_note_ask` | | GET | `/api/v1/notes/{id}` | Read a note by id (or by vault and path with id omitted: GET /notes/-) | `globe_note_get` | | PATCH | `/api/v1/notes/{id}` | Change part of a note with anchored edits, all or nothing | `globe_note_edit` | | PATCH | `/api/v1/notes/{id}/properties` | Set or remove a note's properties (frontmatter) by name | `globe_note_property_update` | | POST | `/api/v1/notes/{id}/trash` | Move a note to the trash | `globe_note_delete` | | GET | `/api/v1/notes/{id}/versions` | List a note's saved versions | `globe_version_list` | | POST | `/api/v1/notes/{id}/versions/{version}/restore` | Restore an earlier version of a note | `globe_version_restore` | | GET | `/api/v1/notes/{id}/freshness` | How fresh a note is | `globe_note_freshness` | | POST | `/api/v1/notes/{id}/confirm` | Confirm a note is still right | `globe_note_confirm` | | GET | `/api/v1/notes/{id}/publish` | A note's publish state | `globe_note_publish_get` | | POST | `/api/v1/notes/{id}/publish` | Publish a note to a public link | `globe_note_publish` | | POST | `/api/v1/notes/{id}/unpublish` | Unpublish a note | `globe_note_unpublish` | | GET | `/api/v1/notes/{id}/shares` | Who a note is shared with | `globe_share_list` | | POST | `/api/v1/notes/{id}/shares` | Share a note with a member or a group | `globe_share_create` | | PATCH | `/api/v1/notes/{id}/shares` | Restrict an org note to the people invited, or open it | `globe_share_update` | | POST | `/api/v1/notes/{id}/shares/remove` | Remove someone's access to a note | `globe_share_delete` | | POST | `/api/v1/notes/move` | Move notes or folders into another vault | `globe_note_move` | | POST | `/api/v1/notes/move/preview` | What moving notes into another vault would do | `globe_note_move_preview` | | POST | `/api/v1/notes/move/undo` | Undo a move between vaults | `globe_note_move_undo` | | GET | `/api/v1/notes/{id}/related` | Notes related to a note, with the reason for each | `globe_note_related` | | GET | `/api/v1/notes/{id}/comments` | A note's comment threads | `globe_comment_list` | | POST | `/api/v1/notes/{id}/comments` | Comment on a note, or reply to a thread | `globe_comment_create` | | GET | `/api/v1/notes/{id}/synced` | Copies of a synced block | `globe_synced_list` | | POST | `/api/v1/notes/{id}/synced/unsync` | Turn a synced block's copies into plain text | `globe_synced_unsync` | **/databases** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/databases` | List databases in a vault | `globe_database_list` | | POST | `/api/v1/databases` | Create a database, inline in a note or as a page, with properties, rows and a view | `globe_database_create` | | POST | `/api/v1/databases/import` | Import CSV or a markdown table as a database, or into one | `globe_database_import` | | GET | `/api/v1/databases/{database}` | Read a database: properties, views, row count, version | `globe_database_get` | | PATCH | `/api/v1/databases/{database}` | Change a database's title and schema: add, rename, retype, delete properties and options | `globe_database_update` | | POST | `/api/v1/databases/{database}/trash` | Move a database to the trash | `globe_database_delete` | | GET | `/api/v1/databases/{database}/rows` | List rows with filter, sort and paging (filter and sort as JSON in the query string) | `globe_row_list` | | POST | `/api/v1/databases/{database}/rows` | Add up to 100 rows | `globe_row_create` | | PATCH | `/api/v1/databases/{database}/rows` | Change up to 100 rows at once (updates) | `globe_row_update` | | PATCH | `/api/v1/databases/{database}/rows/{row}` | Change a row's values, title or page body | `globe_row_update` | | POST | `/api/v1/databases/{database}/rows/{row}/trash` | Delete a row (to the trash) | `globe_row_delete` | | POST | `/api/v1/databases/{database}/rows/trash` | Delete several rows, or all: true to clear the table | `globe_row_delete` | | POST | `/api/v1/databases/validate` | Check a ```base block or .base file and get its warnings | `globe_database_validate` | | POST | `/api/v1/databases/{database}/views` | Add a table, board, list, gallery, calendar, timeline or chart view | `globe_view_create` | | PATCH | `/api/v1/databases/{database}/views/{view}` | Change a view | `globe_view_update` | | GET | `/api/v1/databases/{database}/export` | Export a database as a .base file | `globe_database_export` | | GET | `/api/v1/databases/{database}/automations` | Recent runs of a database's automations | `globe_automation_list` | | GET | `/api/v1/databases/{database}/templates` | A database's row templates | `globe_template_list` | | POST | `/api/v1/databases/{database}/templates` | Add a row template | `globe_template_create` | | PATCH | `/api/v1/databases/{database}/templates/{template}` | Change a row template | `globe_template_update` | | POST | `/api/v1/databases/{database}/templates/{template}/delete` | Delete a row template | `globe_template_delete` | | POST | `/api/v1/databases/{database}/rows/{row}/apply` | Fill a row from a template | `globe_row_apply` | | POST | `/api/v1/databases/{database}/rows/{row}/press` | Press a row's button | `globe_row_press` | **/trash** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/trash` | List trashed notes | `globe_trash_list` | | POST | `/api/v1/trash/{id}/restore` | Restore a trashed note | `globe_note_restore` | | POST | `/api/v1/trash/{id}/purge` | Delete a trashed note for good | `globe_trash_purge` | **/shared** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/shared` | Notes shared with you | `globe_shared_list` | **/links** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/links/resolve` | Resolve a [[wikilink]] to a note | `globe_link_resolve` | **/graph** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/graph` | The link graph of a vault | `globe_graph_get` | **/folders** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/folders/move` | Rename or move a folder with its notes | `globe_folder_move` | **/favorites** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/favorites` | Your favourite notes | `globe_favorite_list` | | POST | `/api/v1/favorites` | Replace your favourite notes | `globe_favorite_set` | **/dashboards** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/dashboards` | Pages that hold live insights (Experiments and Tasks) | `globe_dashboard_list` | **/import** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/import/jobs` | Move in from Notion imports | `globe_import_job_list` | | GET | `/api/v1/import/jobs/{id}` | One Move in from Notion import | `globe_import_job_get` | | PATCH | `/api/v1/import/jobs/{id}` | Pause, resume or cancel a Notion import | `globe_import_job_update` | **/team-vaults** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/team-vaults` | Team vaults you open | `globe_team_list` | | POST | `/api/v1/team-vaults` | Start a team vault on an org team, or on a new one | `globe_team_create` | | PATCH | `/api/v1/team-vaults/{team}` | Rename a team vault | `globe_team_update` | | POST | `/api/v1/team-vaults/{team}/delete` | Close an empty team vault (the team stays) | `globe_team_delete` | | GET | `/api/v1/team-vaults/{team}/members` | Who opens a team vault (parent teams included) | `globe_team_member_list` | | POST | `/api/v1/team-vaults/{team}/members` | Add someone to a team vault, or change their role | `globe_team_member_add` | | POST | `/api/v1/team-vaults/{team}/members/remove` | Take someone out of a team vault, or leave it | `globe_team_member_remove` | **/comments** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/comments/{comment}` | Edit your comment | `globe_comment_update` | | POST | `/api/v1/comments/{comment}/delete` | Delete a comment or its thread | `globe_comment_delete` | | POST | `/api/v1/comments/{comment}/reactions` | Toggle your emoji reaction on a comment | `globe_comment_react` | **/comment-threads** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/comment-threads/{thread}` | Resolve or reopen a comment thread | `globe_comment_resolve` | **/notifications** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/notifications` | Your comment notifications | `globe_notification_list` | | POST | `/api/v1/notifications/read` | Mark comment notifications read | `globe_notification_read` | **/suggestions** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/suggestions` | A vault's Inbox | `globe_suggestion_list` | | POST | `/api/v1/suggestions/{id}/apply` | Apply an Inbox suggestion | `globe_suggestion_apply` | | POST | `/api/v1/suggestions/{id}/reject` | Reject an Inbox suggestion | `globe_suggestion_reject` | | POST | `/api/v1/suggestions/{id}/undo` | Undo a decided suggestion | `globe_suggestion_undo` | | POST | `/api/v1/suggestions/apply-all` | Apply every pending suggestion of a vault | `globe_suggestion_apply_all` | **/sources** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/sources` | A vault's sources | `globe_source_list` | | POST | `/api/v1/sources` | Capture text as a source for the loop | `globe_source_create` | | GET | `/api/v1/sources/{id}` | Read a source | `globe_source_get` | **/files** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/files` | A Notes file, or a note's pictures: names, types, sizes and short-lived download URLs (no image blocks over REST) | `globe_file_get` | | POST | `/api/v1/files` | Store a file in a vault: an upload_id (after the PUT), a public url, or small base64; optionally add it to a note | `globe_file_upload` | | POST | `/api/v1/files/uploads` | Prepare a one-time upload URL for a file's raw bytes (PUT them with curl -T) | `globe_file_prepare` | **/settings** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/settings` | the Notes loop settings | `globe_setting_get` | | PATCH | `/api/v1/settings` | Change the Notes loop settings | `globe_setting_update` | **/imports** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/imports` | Chat-history import status of a vault | `globe_import_list` | | POST | `/api/v1/imports/conversations` | Queue chat conversations as sources | `globe_conversation_import` | | POST | `/api/v1/imports/pages` | Write a batch of notes and databases read from an export | `globe_page_import` | ## MCP tools {#tools} 92 tools: 37 read, 55 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `globe_automation_list` | A database's automation runs | read | `globe:read` | `GET /api/v1/databases/{database}/automations` | | `globe_comment_create` | Comment on a note | write | `globe:write` | `POST /api/v1/notes/{id}/comments` | | `globe_comment_delete` | Delete a comment | write (destructive) | `globe:write` | `POST /api/v1/comments/{comment}/delete` | | `globe_comment_list` | List a note's comment threads | read | `globe:read` | `GET /api/v1/notes/{id}/comments` | | `globe_comment_react` | React to a comment | write | `globe:write` | `POST /api/v1/comments/{comment}/reactions` | | `globe_comment_resolve` | Resolve or reopen a thread | write | `globe:write` | `PATCH /api/v1/comment-threads/{thread}` | | `globe_comment_update` | Edit a comment | write | `globe:write` | `PATCH /api/v1/comments/{comment}` | | `globe_conversation_import` | Import chat conversations | write | `globe:write` | `POST /api/v1/imports/conversations` | | `globe_dashboard_list` | List dashboard pages | read | `globe:read` | `GET /api/v1/dashboards` | | `globe_database_create` | Create a Notes database | write | `globe:write` | `POST /api/v1/databases` | | `globe_database_delete` | Delete a Notes database | write (destructive) | `globe:write` | `POST /api/v1/databases/{database}/trash` | | `globe_database_export` | Export a database as a .base file | read | `globe:read` | `GET /api/v1/databases/{database}/export` | | `globe_database_get` | Read a Notes database | read | `globe:read` | `GET /api/v1/databases/{database}` | | `globe_database_import` | Import a table into a Notes database | write | `globe:write` | `POST /api/v1/databases/import` | | `globe_database_list` | List Notes databases | read | `globe:read` | `GET /api/v1/databases` | | `globe_database_update` | Change a Notes database | write (destructive) | `globe:write` | `PATCH /api/v1/databases/{database}` | | `globe_database_validate` | Check a ```base block | read | `globe:read` | `POST /api/v1/databases/validate` | | `globe_favorite_list` | List favourite notes | read | `globe:read` | `GET /api/v1/favorites` | | `globe_favorite_set` | Set favourite notes | write | `globe:write` | `POST /api/v1/favorites` | | `globe_file_get` | See a file or a note's pictures | read | `globe:read` | `GET /api/v1/files` | | `globe_file_prepare` | Prepare a file upload | write | `globe:write` | `POST /api/v1/files/uploads` | | `globe_file_upload` | Upload a file | write | `globe:write` | `POST /api/v1/files` | | `globe_folder_move` | Rename or move a folder | write | `globe:write` | `POST /api/v1/folders/move` | | `globe_graph_get` | The link graph of a vault | read | `globe:read` | `GET /api/v1/graph` | | `globe_import_job_get` | Read a Notion import | read | `globe:read` | `GET /api/v1/import/jobs/{id}` | | `globe_import_job_list` | List Notion imports | read | `globe:read` | `GET /api/v1/import/jobs` | | `globe_import_job_update` | Pause, resume or cancel a Notion import | write | `globe:write` | `PATCH /api/v1/import/jobs/{id}` | | `globe_import_list` | Import status | read | `globe:read` | `GET /api/v1/imports` | | `globe_link_resolve` | Resolve a [[wikilink]] | read | `globe:read` | `GET /api/v1/links/resolve` | | `globe_note_ask` | Ask Notes | read | `globe:read` | `POST /api/v1/notes/ask` | | `globe_note_confirm` | Confirm a note is still right | write | `globe:write` | `POST /api/v1/notes/{id}/confirm` | | `globe_note_delete` | Move a note to the trash | write (destructive) | `globe:write` | `POST /api/v1/notes/{id}/trash` | | `globe_note_edit` | Edit part of a note | write | `globe:write` | `PATCH /api/v1/notes/{id}` | | `globe_note_freshness` | How fresh a note is | read | `globe:read` | `GET /api/v1/notes/{id}/freshness` | | `globe_note_get` | Read a note | read | `globe:read` | `GET /api/v1/notes/{id}` | | `globe_note_list` | List notes | read | `globe:read` | `GET /api/v1/notes` | | `globe_note_move` | Move notes into another vault | write | `globe:write` | `POST /api/v1/notes/move` | | `globe_note_move_preview` | Preview a move into another vault | read | `globe:read` | `POST /api/v1/notes/move/preview` | | `globe_note_move_undo` | Undo a move between vaults | write | `globe:write` | `POST /api/v1/notes/move/undo` | | `globe_note_property_update` | Set a note's properties | write | `globe:write` | `PATCH /api/v1/notes/{id}/properties` | | `globe_note_publish` | Publish a note to a public link | write | `globe:write` | `POST /api/v1/notes/{id}/publish` | | `globe_note_publish_get` | Read a note's publish state | read | `globe:read` | `GET /api/v1/notes/{id}/publish` | | `globe_note_related` | Notes related to a note | read | `globe:read` | `GET /api/v1/notes/{id}/related` | | `globe_note_restore` | Restore a note from the trash | write | `globe:write` | `POST /api/v1/trash/{id}/restore` | | `globe_note_search` | Search notes | read | `globe:read` | `GET /api/v1/notes/search` | | `globe_note_unpublish` | Unpublish a note | write | `globe:write` | `POST /api/v1/notes/{id}/unpublish` | | `globe_note_write` | Write a note | write (destructive) | `globe:write` | `POST /api/v1/notes` | | `globe_notification_list` | Comment notifications | read | `globe:read` | `GET /api/v1/notifications` | | `globe_notification_read` | Mark notifications read | write | `globe:write` | `POST /api/v1/notifications/read` | | `globe_page_import` | Import pages and databases | write | `globe:write` | `POST /api/v1/imports/pages` | | `globe_row_apply` | Fill a row from a template | write | `globe:write` | `POST /api/v1/databases/{database}/rows/{row}/apply` | | `globe_row_create` | Add rows to a Notes database | write | `globe:write` | `POST /api/v1/databases/{database}/rows` | | `globe_row_delete` | Delete a row of a Notes database | write (destructive) | `globe:write` | `POST /api/v1/databases/{database}/rows/{row}/trash` (+1) | | `globe_row_list` | List rows of a Notes database | read | `globe:read` | `GET /api/v1/databases/{database}/rows` | | `globe_row_press` | Press a row's button | write | `globe:write` | `POST /api/v1/databases/{database}/rows/{row}/press` | | `globe_row_update` | Change a row of a Notes database | write | `globe:write` | `PATCH /api/v1/databases/{database}/rows` (+1) | | `globe_setting_get` | Read the Notes loop settings | read | `globe:read` | `GET /api/v1/settings` | | `globe_setting_update` | Change the Notes loop settings | write | `globe:write` | `PATCH /api/v1/settings` | | `globe_share_create` | Share a note with someone | write | `globe:write` | `POST /api/v1/notes/{id}/shares` | | `globe_share_delete` | Remove someone's access to a note | write (destructive) | `globe:write` | `POST /api/v1/notes/{id}/shares/remove` | | `globe_share_list` | Who a note is shared with | read | `globe:read` | `GET /api/v1/notes/{id}/shares` | | `globe_share_update` | Restrict or open an org note | write | `globe:write` | `PATCH /api/v1/notes/{id}/shares` | | `globe_shared_list` | Notes shared with me | read | `globe:read` | `GET /api/v1/shared` | | `globe_source_create` | Capture text as a source | write | `globe:write` | `POST /api/v1/sources` | | `globe_source_get` | Read a source | read | `globe:read` | `GET /api/v1/sources/{id}` | | `globe_source_list` | List sources | read | `globe:read` | `GET /api/v1/sources` | | `globe_suggestion_apply` | Apply a suggestion | write | `globe:write` | `POST /api/v1/suggestions/{id}/apply` | | `globe_suggestion_apply_all` | Apply every pending suggestion | write | `globe:write` | `POST /api/v1/suggestions/apply-all` | | `globe_suggestion_create` | Suggest changes to notes | write | `globe:write` | `POST /api/v1/notes/suggestions` | | `globe_suggestion_list` | List the Inbox | read | `globe:read` | `GET /api/v1/suggestions` | | `globe_suggestion_reject` | Reject a suggestion | write | `globe:write` | `POST /api/v1/suggestions/{id}/reject` | | `globe_suggestion_undo` | Undo a suggestion | write | `globe:write` | `POST /api/v1/suggestions/{id}/undo` | | `globe_synced_list` | Copies of a synced block | read | `globe:read` | `GET /api/v1/notes/{id}/synced` | | `globe_synced_unsync` | Unsync a block | write | `globe:write` | `POST /api/v1/notes/{id}/synced/unsync` | | `globe_team_create` | Start a team vault | write | `globe:write` | `POST /api/v1/team-vaults` | | `globe_team_delete` | Close an empty team vault | write (destructive) | `globe:write` | `POST /api/v1/team-vaults/{team}/delete` | | `globe_team_list` | List team vaults | read | `globe:read` | `GET /api/v1/team-vaults` | | `globe_team_member_add` | Add someone to a team vault | write | `globe:write` | `POST /api/v1/team-vaults/{team}/members` | | `globe_team_member_list` | List a team vault's people | read | `globe:read` | `GET /api/v1/team-vaults/{team}/members` | | `globe_team_member_remove` | Take someone out of a team vault | write (destructive) | `globe:write` | `POST /api/v1/team-vaults/{team}/members/remove` | | `globe_team_update` | Rename a team vault | write | `globe:write` | `PATCH /api/v1/team-vaults/{team}` | | `globe_template_create` | Add a row template | write | `globe:write` | `POST /api/v1/databases/{database}/templates` | | `globe_template_delete` | Delete a row template | write (destructive) | `globe:write` | `POST /api/v1/databases/{database}/templates/{template}/delete` | | `globe_template_list` | A database's row templates | read | `globe:read` | `GET /api/v1/databases/{database}/templates` | | `globe_template_update` | Change a row template | write | `globe:write` | `PATCH /api/v1/databases/{database}/templates/{template}` | | `globe_trash_list` | List the trash | read | `globe:read` | `GET /api/v1/trash` | | `globe_trash_purge` | Delete a trashed note for good | write (destructive) | `globe:write` | `POST /api/v1/trash/{id}/purge` | | `globe_vault_list` | List Notes vaults | read | `globe:read` | `GET /api/v1/vaults` | | `globe_version_list` | List a note's versions | read | `globe:read` | `GET /api/v1/notes/{id}/versions` | | `globe_version_restore` | Restore a note's earlier version | write | `globe:write` | `POST /api/v1/notes/{id}/versions/{version}/restore` | | `globe_view_create` | Add a view to a Notes database | write | `globe:write` | `POST /api/v1/databases/{database}/views` | | `globe_view_update` | Change a view of a Notes database | write | `globe:write` | `PATCH /api/v1/databases/{database}/views/{view}` | ## Related {#related} - [Use Notes from any agent](/docs/integrations/globe-mcp.md): connect Claude Code, Cursor or an OAuth app, and troubleshooting. - [Notes databases for agents](/docs/cloud/globe-databases-mcp.md): property types, filters and sorts, and a full database example. - [Notes pages for agents](/docs/cloud/globe-pages-mcp.md): trash, versions, publishing, sharing, comments and the Inbox. - [Venom Notes API](/docs/cloud/globe-api.md): the app's console API, vaults and access in detail. - [The REST twin](/docs/developers/rest.md) and [Venom for agents](/docs/cloud/workspace-mcp.md): the shared envelope, `If-Match` and `Idempotency-Key`. - [Authentication and scopes](/docs/developers/auth.md), [Webhooks](/docs/developers/webhooks.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Venom Tasks URL: https://cloud.usevenom.dev/docs/developers/tasks Description: Create, find and update Tasks issues from code, and run agents that claim delegated work, report progress and hand it back, over REST or MCP. Venom Tasks is your organisation's issue tracker. An issue has a person as its assignee, who owns it, and can be delegated to an agent, which does the work. Every action of the Tasks app is an MCP tool and a REST route, so a script can file issues and an agent can pick up work, claim it, report progress and move it to review. ## What you can build {#build} - **An agent worker.** List the issues delegated to it (`GET /api/v1/issues/mine`), claim one (`POST /api/v1/issues/{id}/claim`), report progress and move it to review (`POST /api/v1/issues/{id}/progress`). - **Issues from other systems.** File an issue from a failed job or a support ticket (`POST /api/v1/issues`) with a team, labels, a priority and a delegate. - **Bulk changes.** Relabel, move or reprioritise up to 50 issues in one call, all or nothing (`POST /api/v1/tasks/issues/batch`). - **Planning reports.** Read cycles, projects and their milestones (`GET /api/v1/tasks/teams/{id}/cycles`, `GET /api/v1/tasks/projects`) and the team insights (`GET /api/v1/tasks/insights`). - **A push-driven worker.** Hold `GET /tasks/mcp/assigned` open and start work within seconds of an issue being delegated, with no polling. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/tasks`, server name `venom-tasks` | | Connect | `claude mcp add --transport http venom-tasks https://cloud.usevenom.dev/workspace/mcp/tasks` | | MCP tools | 221 (81 read, 140 write) | | OAuth scopes | `tasks:read` `tasks:write` | | REST twin | 228 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `tasks.issue.created`, `tasks.issue.updated`, `tasks.issue.deleted`, `tasks.comment.created`, `tasks.issue.delegated` | ## Authentication and scopes {#scopes} Every credential becomes an agent with an id, and that id is what issues are delegated to and what comments record: | Credential | Agent | What it may do | |---|---|---| | Personal API key | `key:`, a personal agent for its member | what the member's role allows | | OAuth app | a personal agent for the member who connected it | the member's role, narrowed by `tasks:read` and `tasks:write` | | Team key bound to a service agent | the service agent | read and write in the teams the admin picked; read only if the admin made it read-only | | Team key with no service agent | none | read only, and it cannot claim | | Any key with `x-venom-agent: daemon:` or `session:` | that venom daemon or session | what the key allows | The member's role sets the ceiling: owners and admins have `tasks:read`, `tasks:write` and `tasks:admin`; developers read and write; billing and viewer members read only. Team settings, workflow states and agents need `tasks:admin`. A read-only caller is refused every write with a message that says why. A private team's issues answer as if they did not exist for anyone who is not in the team and has no `tasks:admin`. An admin binds a team key to a service agent with `tasks_agent_create` (or `POST /api/v1/tasks/agents`), and can limit it to some teams, some apps or read only with `tasks_agent_update`. A service agent limited to some teams sees only those teams' issues. Tasks is included in the Team plan and up. Without it, the handshake still works and every tool answers with a message that says where to add it; over REST that is `403 forbidden`. ## Worked example {#example} An agent's loop: find work, claim it, report, and hand it to review. ```bash # 1. The open issues delegated to this agent, and those assigned to its member curl "$VENOM_CLOUD/api/v1/issues/mine?limit=10" \ -H "Authorization: Bearer $VENOM_API_KEY" # 2. Claim one: it is delegated to you and moved to the team's first started state curl -X POST "$VENOM_CLOUD/api/v1/issues/ENG-42/claim" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -d '{}' # 3. Report progress, and move it to review when done curl -X POST "$VENOM_CLOUD/api/v1/issues/ENG-42/progress" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Idempotency-Key: eng-42-review' \ -d '{"body": "Fix pushed and tests pass. Ready for review.", "state": "In Review"}' ``` The same claim and report over MCP, from any client connected to `/workspace/mcp/tasks`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "tasks_issue_claim", "arguments": { "id": "ENG-42" } } } ``` ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "tasks_issue_progress", "arguments": { "id": "ENG-42", "body": "Fix pushed and tests pass. Ready for review.", "state": "In Review" } } } ``` `id` is the issue's identifier (`ENG-42`) or its id. `state` is a workflow state of the issue's team by name, or a type: `backlog`, `unstarted`, `started`, `completed`, `canceled`, `triage`. ## Claims and leases {#claims} - A claim is a **30-minute lease**. While it is live, another agent's claim is refused and the message names the holder and when the lease ends (`403` over REST). - Each write by the agent holding the claim renews the lease, so report progress at least every 30 minutes. - When a lease runs out, the claim is cleared but the delegate stays, and the issue's assignee (its creator when nobody is assigned) gets a "claim expired" item in their Inbox. - Claiming never changes the assignee. Set `delegate` and `assignee` apart with `PATCH /api/v1/issues/{id}`. - A closed issue cannot be claimed; reopen it with a `state` first. - A service agent's guidance, set by an admin, is shown at the end of `tasks_issue_get`. ## Push: issues delegated to you {#push} `GET /tasks/mcp/assigned` is a server-sent event stream for one agent, with the same credentials as the MCP endpoint. It needs an agent, so a team key with no service agent gets `403`. It sends an `assigned` event for each open issue delegated to the agent that has no live claim, first the ones already delegated and then each new delegation: ```text id: 4121 event: assigned data: {"seq":4121,"issueId":"…","identifier":"ENG-42","title":"…","teamId":"…","stateType":"unstarted","priority":1} ``` Reconnect with `Last-Event-ID` (or `?after=`) to skip what you have seen. The stream pings every 25 seconds and closes after about 4.5 minutes; reconnect. Each connection counts as one request in the agent's rate limit. ## Limits {#limits} - 240 requests a minute per agent, and 960 per credential over all its agents, then `429` with `retry-after`. - 1 MiB per request; a comment is at most 64 KB. - A write that contains a credential is refused before anything is stored. - Every write is recorded in the organisation's audit log under the credential and agent, with ids, never the text. Venom Tasks' own MCP endpoint, `POST /tasks/mcp`, serves the same tools; `/workspace/mcp/tasks` shares one credential with the other products. Setup for clients is in [Venom Tasks for agents](/docs/cloud/tasks-mcp.md). ## Events {#events} 5 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `tasks.issue.created` | A Venom Tasks issue was created, by a person or an agent: identifier, title, team, state, priority, assignee and delegate. Never the description. | | `tasks.issue.updated` | A Venom Tasks issue changed: its state, assignee, delegate (and whether an agent holds a claim on it), priority, labels or text. Several changes within a minute arrive as one event with the issue as it is now. | | `tasks.issue.deleted` | A Venom Tasks issue was deleted: its id and identifier. | | `tasks.comment.created` | A comment was added to a Venom Tasks issue, by a person or an agent's progress report: the issue, the comment id and who wrote it. Never the comment's text. | | `tasks.issue.delegated` | A Venom Tasks issue was delegated to an agent (at creation or later, each new delegate): the issue, its identifier and title, the delegate agent's id, the previous delegate and who delegated it, so an agent learns of new work without holding a stream open. Never the description. | Besides org webhooks, an agent can follow its own work on the `GET /tasks/mcp/assigned` stream above, and any caller can poll `GET /api/v1/changes` for issue and note changes after a cursor. GitHub sends its webhooks into Tasks to link pull requests and turn labelled GitHub issues into delegated work ([GitHub issues as intents](/docs/cloud/tasks-github.md#intents)). ## REST routes {#rest} The REST twin: 228 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/teams** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/teams` | List the teams you can see, with their states | `tasks_team_list` | **/issues** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/issues` | Find issues by text and filters (filter: the list's JSON filter tree) | `tasks_issue_search` | | POST | `/api/v1/issues` | Create an issue | `tasks_issue_create` | | GET | `/api/v1/issues/mine` | List the issues delegated to this agent and assigned to its member | `tasks_issue_list_mine` | | GET | `/api/v1/issues/{id}` | Read one issue | `tasks_issue_get` | | PATCH | `/api/v1/issues/{id}` | Change an issue; edits patch its description | `tasks_issue_update` | | POST | `/api/v1/issues/{id}/comments` | Comment on an issue | `tasks_comment_create` | | POST | `/api/v1/issues/{id}/claim` | Claim an issue with a 30-minute lease | `tasks_issue_claim` | | POST | `/api/v1/issues/{id}/progress` | Post a progress comment, optionally moving the state | `tasks_issue_progress` | **/tasks/issues** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/tasks/issues/batch` | Change many issues at once | `tasks_issue_batch` | | POST | `/api/v1/tasks/issues/move` | Move issues to another team | `tasks_issue_move` | | DELETE | `/api/v1/tasks/issues/{id}` | Delete an issue | `tasks_issue_delete` | | GET | `/api/v1/tasks/issues/{id}/history` | List an issue's description versions | `tasks_issue_history` | | POST | `/api/v1/tasks/issues/{id}/history/{version_id}/restore` | Restore an earlier description | `tasks_issue_revert` | | POST | `/api/v1/tasks/issues/{id}/subscribe` | Subscribe to an issue | `tasks_issue_subscribe` | | DELETE | `/api/v1/tasks/issues/{id}/subscribe` | Unsubscribe from an issue | `tasks_issue_unsubscribe` | | POST | `/api/v1/tasks/issues/{id}/triage` | Triage an issue | `tasks_issue_triage` | | GET | `/api/v1/tasks/issues/{id}/activity` | List an issue's activity | `tasks_activity_list` | | POST | `/api/v1/tasks/issues/{id}/relations` | Relate two issues | `tasks_relation_create` | | POST | `/api/v1/tasks/issues/{id}/duplicate` | Make a copy of an issue | `tasks_issue_duplicate` | | POST | `/api/v1/tasks/issues/{id}/convert-to-project` | Convert an issue to a project | `tasks_issue_convert_to_project` | | GET | `/api/v1/tasks/issues/{id}/comments` | List an issue's comments | `tasks_comment_list` | | POST | `/api/v1/tasks/issues/{issue_id}/reactions` | React with an emoji | `tasks_reaction_add` | | DELETE | `/api/v1/tasks/issues/{issue_id}/reactions` | Remove a reaction | `tasks_reaction_remove` | | GET | `/api/v1/tasks/issues/{id}/attachments` | List an issue's attachments | `tasks_attachment_list` | | POST | `/api/v1/tasks/issues/{id}/attachments` | Attach a file to an issue | `tasks_attachment_create` | | GET | `/api/v1/tasks/issues/{id}/links` | List an issue's links | `tasks_link_list` | | POST | `/api/v1/tasks/issues/{id}/links` | Add a link to an issue | `tasks_link_create` | | GET | `/api/v1/tasks/issues/{id}/requests` | List an issue's customer requests | `tasks_request_list` | | POST | `/api/v1/tasks/issues/{id}/requests` | Add a customer request to an issue | `tasks_request_create` | | GET | `/api/v1/tasks/issues/{id}/notes` | List an issue's linked notes | `tasks_note_list` | | POST | `/api/v1/tasks/issues/{id}/notes` | Link or create a note for an issue | `tasks_note_link` | | DELETE | `/api/v1/tasks/issues/{id}/notes` | Unlink a note from an issue | `tasks_note_unlink` | | GET | `/api/v1/tasks/issues/{id}/pull-requests` | List an issue's pull requests | `tasks_pullrequest_list` | | POST | `/api/v1/tasks/issues/{id}/pull-requests` | Refresh an issue's pull requests | `tasks_pullrequest_link` | | DELETE | `/api/v1/tasks/issues/{id}/pull-requests/{pr_id}` | Unlink a pull request from an issue | `tasks_pullrequest_unlink` | | GET | `/api/v1/tasks/issues/{id}/suggestions` | List AI suggestions for an issue | `tasks_suggestion_list` | | POST | `/api/v1/tasks/issues/{id}/suggestions` | Ask for AI suggestions | `tasks_suggestion_create` | | POST | `/api/v1/tasks/issues/{id}/apply-template` | Apply a template to an issue | `tasks_template_apply` | | GET | `/api/v1/tasks/issues/export` | Export a list of issues as CSV | `tasks_issue_export` | **/tasks/relations** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/tasks/relations/{id}` | Remove an issue relation | `tasks_relation_delete` | **/tasks/dependencies** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/dependencies` | List issue dependencies | `tasks_dependency_list` | **/tasks/insights** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/insights` | Read Tasks insights | `tasks_insight_get` | | GET | `/api/v1/tasks/insights/flow` | Read a cumulative flow | `tasks_flow_insight_get` | **/tasks/projects** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/projects/{id}/insights` | Read a project's insights | `tasks_project_insight_get` | | POST | `/api/v1/tasks/projects/{id}/follow` | Follow a project | `tasks_project_follow` | | DELETE | `/api/v1/tasks/projects/{id}/follow` | Unfollow a project | `tasks_project_unfollow` | | GET | `/api/v1/tasks/projects/{id}/requests` | List a project's customer requests | `tasks_projectrequest_list` | | POST | `/api/v1/tasks/projects/{id}/requests` | Add a customer request to a project | `tasks_projectrequest_create` | | GET | `/api/v1/tasks/projects` | List projects | `tasks_project_list` | | POST | `/api/v1/tasks/projects` | Create a project | `tasks_project_create` | | GET | `/api/v1/tasks/projects/{id}` | Read a project | `tasks_project_get` | | PATCH | `/api/v1/tasks/projects/{id}` | Change a project | `tasks_project_update` | | DELETE | `/api/v1/tasks/projects/{id}` | Delete a project | `tasks_project_delete` | | POST | `/api/v1/tasks/projects/{id}/move` | Move a project to another team | `tasks_project_move` | | GET | `/api/v1/tasks/projects/{id}/activity` | List a project's activity | `tasks_project_activity` | | GET | `/api/v1/tasks/projects/{project_id}/milestones` | List milestones | `tasks_milestone_list` | | POST | `/api/v1/tasks/projects/{project_id}/milestones` | Add a milestone | `tasks_milestone_create` | | GET | `/api/v1/tasks/projects/{id}/updates` | List a project's status updates | `tasks_projectupdate_list` | | POST | `/api/v1/tasks/projects/{id}/updates` | Post a project status update | `tasks_projectupdate_create` | | GET | `/api/v1/tasks/projects/{project}/dependencies` | List project dependencies | `tasks_projectdep_list` | | POST | `/api/v1/tasks/projects/{project}/dependencies` | Add a project dependency | `tasks_projectdep_add` | | DELETE | `/api/v1/tasks/projects/{project}/dependencies` | Remove a project dependency | `tasks_projectdep_remove` | | GET | `/api/v1/tasks/projects/dependencies` | List project dependencies | `tasks_projectdep_list` | | GET | `/api/v1/tasks/projects/{id}/links` | List a project's links | `tasks_projectlink_list` | | POST | `/api/v1/tasks/projects/{id}/links` | Add a link to a project | `tasks_projectlink_create` | | GET | `/api/v1/tasks/projects/{id}/documents` | List a project's documents | `tasks_document_list` | | POST | `/api/v1/tasks/projects/{id}/documents` | Add a document to a project | `tasks_document_link` | | DELETE | `/api/v1/tasks/projects/{id}/documents` | Remove a document from a project | `tasks_document_unlink` | | GET | `/api/v1/tasks/projects/export` | Export projects as CSV | `tasks_project_export` | **/tasks/cycles** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/cycles/{id}/insights` | Read a cycle's insights | `tasks_cycle_insight_get` | | GET | `/api/v1/tasks/cycles/{id}` | Read a cycle | `tasks_cycle_get` | | PATCH | `/api/v1/tasks/cycles/{id}` | Change a cycle | `tasks_cycle_update` | | DELETE | `/api/v1/tasks/cycles/{id}` | Delete a cycle | `tasks_cycle_delete` | | POST | `/api/v1/tasks/cycles/{id}/start` | Start the next cycle today | `tasks_cycle_start` | | POST | `/api/v1/tasks/cycles/{id}/complete` | Complete a cycle | `tasks_cycle_complete` | **/tasks/saved-insights** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/saved-insights` | List saved insights | `tasks_saved_insight_list` | | POST | `/api/v1/tasks/saved-insights` | Save an insight | `tasks_saved_insight_create` | | GET | `/api/v1/tasks/saved-insights/{id}` | Read a saved insight | `tasks_saved_insight_get` | | PATCH | `/api/v1/tasks/saved-insights/{id}` | Change a saved insight | `tasks_saved_insight_update` | | DELETE | `/api/v1/tasks/saved-insights/{id}` | Delete a saved insight | `tasks_saved_insight_delete` | | GET | `/api/v1/tasks/saved-insights/{id}/result` | Run a saved insight | `tasks_saved_insight_run` | **/tasks/reminders** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/reminders` | List your reminders | `tasks_reminder_list` | | PUT | `/api/v1/tasks/reminders` | Set a reminder | `tasks_reminder_set` | | DELETE | `/api/v1/tasks/reminders/{id}` | Cancel a reminder | `tasks_reminder_delete` | **/tasks/pulse** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/pulse` | Read your Pulse | `tasks_pulse_get` | | GET | `/api/v1/tasks/pulse/follows` | List what is in your Pulse | `tasks_follow_list` | | GET | `/api/v1/tasks/pulse/digests` | List your weekly Pulse digests | `tasks_pulse_digest_list` | | POST | `/api/v1/tasks/pulse/digests` | Make last week's Pulse digest | `tasks_pulse_digest_create` | | GET | `/api/v1/tasks/pulse/digests/{id}` | Read a Pulse digest | `tasks_pulse_digest_get` | | PATCH | `/api/v1/tasks/pulse/digests/{id}` | Mark a Pulse digest read | `tasks_pulse_digest_update` | | GET | `/api/v1/tasks/pulse/settings` | Read the org's Pulse settings | `tasks_pulse_settings_get` | | PUT | `/api/v1/tasks/pulse/settings` | Change the org's Pulse settings | `tasks_pulse_settings_update` | **/tasks/initiatives** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/tasks/initiatives/{id}/follow` | Follow an initiative | `tasks_initiative_follow` | | DELETE | `/api/v1/tasks/initiatives/{id}/follow` | Unfollow an initiative | `tasks_initiative_unfollow` | | GET | `/api/v1/tasks/initiatives` | List initiatives | `tasks_initiative_list` | | POST | `/api/v1/tasks/initiatives` | Create an initiative | `tasks_initiative_create` | | GET | `/api/v1/tasks/initiatives/{id}` | Read an initiative | `tasks_initiative_get` | | PATCH | `/api/v1/tasks/initiatives/{id}` | Change an initiative | `tasks_initiative_update` | | DELETE | `/api/v1/tasks/initiatives/{id}` | Delete an initiative | `tasks_initiative_delete` | | GET | `/api/v1/tasks/initiatives/{id}/updates` | List an initiative's status updates | `tasks_initiative_update_list` | | POST | `/api/v1/tasks/initiatives/{id}/updates` | Post an initiative status update | `tasks_initiative_update_create` | | GET | `/api/v1/tasks/initiatives/export` | Export initiatives as CSV | `tasks_initiative_export` | **/tasks/comments** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/comments/{id}` | Edit a comment | `tasks_comment_update` | | DELETE | `/api/v1/tasks/comments/{id}` | Delete a comment | `tasks_comment_delete` | | PUT | `/api/v1/tasks/comments/{comment}/mute` | Mute or unmute a comment thread | `tasks_thread_mute` | | POST | `/api/v1/tasks/comments/{comment_id}/reactions` | React with an emoji | `tasks_reaction_add` | | DELETE | `/api/v1/tasks/comments/{comment_id}/reactions` | Remove a reaction | `tasks_reaction_remove` | **/tasks/attachments** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/tasks/attachments/{id}` | Remove an attachment | `tasks_attachment_delete` | **/tasks/links** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/links/{id}` | Edit a link | `tasks_link_update` | | DELETE | `/api/v1/tasks/links/{id}` | Remove a link | `tasks_link_delete` | **/tasks/requests** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/requests/{id}` | Change a customer request's quote | `tasks_request_update` | | DELETE | `/api/v1/tasks/requests/{id}` | Remove a customer request | `tasks_request_delete` | | GET | `/api/v1/tasks/requests/sources` | Find customers to link as requests | `tasks_customer_search` | **/tasks/suggestions** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/tasks/suggestions/{id}` | Accept or dismiss a suggestion | `tasks_suggestion_decide` | **/tasks/teams** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/tasks/teams` | Create a team | `tasks_team_create` | | PATCH | `/api/v1/tasks/teams/{id}` | Change a team | `tasks_team_update` | | DELETE | `/api/v1/tasks/teams/{id}` | Delete a team | `tasks_team_delete` | | GET | `/api/v1/tasks/teams/{id}/members` | List a team's members | `tasks_teammember_list` | | POST | `/api/v1/tasks/teams/{id}/members` | Add a member to a team | `tasks_teammember_add` | | DELETE | `/api/v1/tasks/teams/{id}/members/{member_id}` | Remove a member from a team | `tasks_teammember_remove` | | GET | `/api/v1/tasks/teams/{id}/states` | List a team's workflow states | `tasks_state_list` | | POST | `/api/v1/tasks/teams/{id}/states` | Add a workflow state | `tasks_state_create` | | POST | `/api/v1/tasks/teams/{id}/states/reorder` | Reorder workflow states | `tasks_state_reorder` | | GET | `/api/v1/tasks/teams/{id}/templates` | List issue templates | `tasks_template_list` | | POST | `/api/v1/tasks/teams/{id}/templates` | Create an issue template | `tasks_template_create` | | GET | `/api/v1/tasks/teams/{id}/recurring` | List a team's recurring issues | `tasks_recurring_list` | | POST | `/api/v1/tasks/teams/{id}/recurring` | Create a recurring issue | `tasks_recurring_create` | | GET | `/api/v1/tasks/teams/{id}/sla` | Read a team's SLA rules | `tasks_sla_get` | | PUT | `/api/v1/tasks/teams/{id}/sla` | Set a team's SLA rules | `tasks_sla_set` | | GET | `/api/v1/tasks/teams/{id}/triage-rules` | List a team's triage rules | `tasks_triagerule_list` | | POST | `/api/v1/tasks/teams/{id}/triage-rules` | Create a triage rule | `tasks_triagerule_create` | | POST | `/api/v1/tasks/teams/{id}/triage-rules/reorder` | Reorder a team's triage rules | `tasks_triagerule_reorder` | | POST | `/api/v1/tasks/teams/{id}/triage-rules/test` | Try a triage rule | `tasks_triagerule_test` | | GET | `/api/v1/tasks/teams/{id}/ai-triage` | Read a team's AI triage settings | `tasks_triage_get` | | PUT | `/api/v1/tasks/teams/{id}/ai-triage` | Set a team's AI triage settings | `tasks_triage_set` | | GET | `/api/v1/tasks/teams/{id}/cycles` | List a team's cycles | `tasks_cycle_list` | | POST | `/api/v1/tasks/teams/{id}/cycles` | Create a cycle | `tasks_cycle_create` | | POST | `/api/v1/tasks/teams/{id}/cycles/schedule` | Schedule upcoming cycles | `tasks_cycle_schedule` | **/tasks/members** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/members` | List the organisation's members | `tasks_member_list` | | GET | `/api/v1/tasks/members/export` | Export members as CSV | `tasks_member_export` | **/tasks/states** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/states/{id}` | Change a workflow state | `tasks_state_update` | | DELETE | `/api/v1/tasks/states/{id}` | Delete a workflow state | `tasks_state_delete` | **/tasks/labels** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/labels` | List labels | `tasks_label_list` | | POST | `/api/v1/tasks/labels` | Create a label | `tasks_label_create` | | PATCH | `/api/v1/tasks/labels/{id}` | Change a label | `tasks_label_update` | | DELETE | `/api/v1/tasks/labels/{id}` | Delete a label | `tasks_label_delete` | **/tasks/label-groups** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/label-groups` | List label groups | `tasks_labelgroup_list` | | POST | `/api/v1/tasks/label-groups` | Create a label group | `tasks_labelgroup_create` | | PATCH | `/api/v1/tasks/label-groups/{id}` | Change a label group | `tasks_labelgroup_update` | | DELETE | `/api/v1/tasks/label-groups/{id}` | Delete a label group | `tasks_labelgroup_delete` | **/tasks/templates** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/templates` | List issue templates | `tasks_template_list` | | POST | `/api/v1/tasks/templates` | Create an issue template | `tasks_template_create` | | GET | `/api/v1/tasks/templates/{id}` | Read an issue template | `tasks_template_get` | | PATCH | `/api/v1/tasks/templates/{id}` | Change an issue template | `tasks_template_update` | | DELETE | `/api/v1/tasks/templates/{id}` | Delete an issue template | `tasks_template_delete` | **/tasks/recurring** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/recurring/{id}` | Read a recurring issue | `tasks_recurring_get` | | PATCH | `/api/v1/tasks/recurring/{id}` | Change a recurring issue | `tasks_recurring_update` | | DELETE | `/api/v1/tasks/recurring/{id}` | Delete a recurring issue | `tasks_recurring_delete` | **/tasks/triage-rules** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/triage-rules/{id}` | Read a triage rule | `tasks_triagerule_get` | | PATCH | `/api/v1/tasks/triage-rules/{id}` | Change a triage rule | `tasks_triagerule_update` | | DELETE | `/api/v1/tasks/triage-rules/{id}` | Delete a triage rule | `tasks_triagerule_delete` | **/tasks/milestones** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/milestones` | List milestones | `tasks_milestone_list` | | PATCH | `/api/v1/tasks/milestones/{id}` | Change a milestone | `tasks_milestone_update` | | DELETE | `/api/v1/tasks/milestones/{id}` | Delete a milestone | `tasks_milestone_delete` | **/tasks/project-updates** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/project-updates/{id}` | Edit a project status update | `tasks_projectupdate_update` | | DELETE | `/api/v1/tasks/project-updates/{id}` | Delete a project status update | `tasks_projectupdate_delete` | **/tasks/updates** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/updates/{update_kind}/{update_id}/comments` | List comments on an update | `tasks_updatecomment_list` | | POST | `/api/v1/tasks/updates/{update_kind}/{update_id}/comments` | Comment on an update | `tasks_updatecomment_create` | | PUT | `/api/v1/tasks/updates/{update_kind}/{update_id}/reactions` | React to an update | `tasks_updatereaction_set` | **/tasks/update-comments** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/update-comments/{id}` | Edit a comment on an update | `tasks_updatecomment_update` | | DELETE | `/api/v1/tasks/update-comments/{id}` | Delete a comment on an update | `tasks_updatecomment_delete` | **/tasks/update-schedules** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/update-schedules` | Read update schedules | `tasks_updateschedule_get` | | PUT | `/api/v1/tasks/update-schedules` | Set an update schedule | `tasks_updateschedule_set` | **/tasks/initiative-updates** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/tasks/initiative-updates/{id}` | Edit an initiative status update | `tasks_initiativeupdate_update` | | DELETE | `/api/v1/tasks/initiative-updates/{id}` | Delete an initiative status update | `tasks_initiativeupdate_delete` | **/tasks/views** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/views` | List saved views | `tasks_view_list` | | POST | `/api/v1/tasks/views` | Create a saved view | `tasks_view_create` | | GET | `/api/v1/tasks/views/{id}` | Read a saved view | `tasks_view_get` | | PATCH | `/api/v1/tasks/views/{id}` | Change a saved view | `tasks_view_update` | | DELETE | `/api/v1/tasks/views/{id}` | Delete a saved view | `tasks_view_delete` | | POST | `/api/v1/tasks/views/{id}/duplicate` | Duplicate a saved view | `tasks_view_duplicate` | | POST | `/api/v1/tasks/views/{id}/subscription` | Follow a saved view | `tasks_view_subscribe` | **/tasks/favorites** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/favorites` | List your favourites | `tasks_favorite_list` | | POST | `/api/v1/tasks/favorites` | Favourite something | `tasks_favorite_create` | | PATCH | `/api/v1/tasks/favorites/{id}` | Move a favourite | `tasks_favorite_update` | | DELETE | `/api/v1/tasks/favorites/{id}` | Remove a favourite | `tasks_favorite_delete` | **/tasks/notifications** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/notifications` | List your notifications | `tasks_notification_list` | | PATCH | `/api/v1/tasks/notifications/{id}` | Read, archive or snooze a notification | `tasks_notification_update` | | POST | `/api/v1/tasks/notifications/read-all` | Mark every notification read | `tasks_notification_read_all` | | GET | `/api/v1/tasks/notifications/settings` | Read your notification settings | `tasks_notification_settings_get` | | PUT | `/api/v1/tasks/notifications/settings` | Change your notification settings | `tasks_notification_settings_update` | | PUT | `/api/v1/tasks/notifications/channels` | Turn push or email off for the org | `tasks_notification_channels_update` | **/tasks/import** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/import/jobs` | List imports | `tasks_import_job_list` | | GET | `/api/v1/tasks/import/jobs/{id}` | Read an import | `tasks_import_job_get` | | PATCH | `/api/v1/tasks/import/jobs/{id}` | Pause, resume or cancel an import | `tasks_import_job_update` | **/tasks/export** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/export` | List your workspace exports | `tasks_export_list` | | POST | `/api/v1/tasks/export` | Start a workspace export | `tasks_export_create` | | GET | `/api/v1/tasks/export/{id}` | Read a workspace export | `tasks_export_get` | | DELETE | `/api/v1/tasks/export/{id}` | Cancel or delete a workspace export | `tasks_export_cancel` | **/tasks/agents** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/agents` | List agents | `tasks_agent_list` | | POST | `/api/v1/tasks/agents` | Create a service agent | `tasks_agent_create` | | PATCH | `/api/v1/tasks/agents/{id}` | Change an agent | `tasks_agent_update` | **/tasks/github** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/github` | Read the GitHub connection | `tasks_github_get` | | PATCH | `/api/v1/tasks/github` | Set GitHub automations | `tasks_github_update` | | GET | `/api/v1/tasks/github/summary` | Read the GitHub summary | `tasks_github_summary_get` | | PUT | `/api/v1/tasks/github/intents` | Set GitHub intent labels | `tasks_github_intent_set` | | PUT | `/api/v1/tasks/github/rules` | Set a team's GitHub rules | `tasks_github_rule_set` | **/tasks/releases** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/tasks/releases/pipelines` | List release pipelines | `tasks_releasepipeline_list` | | POST | `/api/v1/tasks/releases/pipelines` | Create a release pipeline | `tasks_releasepipeline_create` | | PATCH | `/api/v1/tasks/releases/pipelines/{pipeline}` | Change a release pipeline | `tasks_releasepipeline_update` | | DELETE | `/api/v1/tasks/releases/pipelines/{pipeline}` | Delete a release pipeline | `tasks_releasepipeline_delete` | | POST | `/api/v1/tasks/releases/pipelines/{pipeline}/restore` | Restore a deleted release pipeline | `tasks_releasepipeline_restore` | | GET | `/api/v1/tasks/releases/pipelines/{pipeline}/releases` | List releases | `tasks_release_list` | | POST | `/api/v1/tasks/releases/pipelines/{pipeline}/releases` | Create a release | `tasks_release_create` | | GET | `/api/v1/tasks/releases` | List releases | `tasks_release_list` | | GET | `/api/v1/tasks/releases/{release}` | Read a release | `tasks_release_get` | | PATCH | `/api/v1/tasks/releases/{release}` | Change a release | `tasks_release_update` | | GET | `/api/v1/tasks/releases/{release}/draft` | Draft release notes | `tasks_release_draft` | | GET | `/api/v1/tasks/releases/pipelines/{pipeline}/changelog` | Read a pipeline's changelog | `tasks_releasechangelog_get` | | GET | `/api/v1/tasks/releases/pipelines/{pipeline}/keys` | List a pipeline's CI keys | `tasks_releasekey_list` | | POST | `/api/v1/tasks/releases/pipelines/{pipeline}/keys` | Create a pipeline CI key | `tasks_releasekey_create` | | DELETE | `/api/v1/tasks/releases/pipelines/{pipeline}/keys/{key}` | Revoke a pipeline CI key | `tasks_releasekey_revoke` | | POST | `/api/v1/tasks/releases/{release}/complete` | Complete a release | `tasks_release_complete` | | POST | `/api/v1/tasks/releases/{release}/issues` | Add issues to a release | `tasks_release_issue_add` | | DELETE | `/api/v1/tasks/releases/{release}/issues` | Remove issues from a release | `tasks_release_issue_remove` | | GET | `/api/v1/tasks/releases/automation/{team}` | Read a team's release automation | `tasks_releaseautomation_get` | | PUT | `/api/v1/tasks/releases/automation/{team}` | Set a team's release automation | `tasks_releaseautomation_update` | ## MCP tools {#tools} 221 tools: 81 read, 140 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `tasks_activity_list` | List an issue's activity | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/activity` | | `tasks_agent_create` | Create a service agent | write | `tasks:write` | `POST /api/v1/tasks/agents` | | `tasks_agent_list` | List agents | read | `tasks:read` | `GET /api/v1/tasks/agents` | | `tasks_agent_update` | Change an agent | write | `tasks:write` | `PATCH /api/v1/tasks/agents/{id}` | | `tasks_attachment_create` | Attach a file to an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/attachments` | | `tasks_attachment_delete` | Remove an attachment | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/attachments/{id}` | | `tasks_attachment_list` | List an issue's attachments | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/attachments` | | `tasks_comment_create` | Comment on an issue | write | `tasks:write` | `POST /api/v1/issues/{id}/comments` | | `tasks_comment_delete` | Delete a comment | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/comments/{id}` | | `tasks_comment_list` | List an issue's comments | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/comments` | | `tasks_comment_update` | Edit a comment | write | `tasks:write` | `PATCH /api/v1/tasks/comments/{id}` | | `tasks_customer_search` | Find customers to link as requests | read | `tasks:read` | `GET /api/v1/tasks/requests/sources` | | `tasks_cycle_complete` | Complete a cycle | write | `tasks:write` | `POST /api/v1/tasks/cycles/{id}/complete` | | `tasks_cycle_create` | Create a cycle | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/cycles` | | `tasks_cycle_delete` | Delete a cycle | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/cycles/{id}` | | `tasks_cycle_get` | Read a cycle | read | `tasks:read` | `GET /api/v1/tasks/cycles/{id}` | | `tasks_cycle_insight_get` | Read a cycle's insights | read | `tasks:read` | `GET /api/v1/tasks/cycles/{id}/insights` | | `tasks_cycle_list` | List a team's cycles | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/cycles` | | `tasks_cycle_schedule` | Schedule upcoming cycles | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/cycles/schedule` | | `tasks_cycle_start` | Start the next cycle today | write | `tasks:write` | `POST /api/v1/tasks/cycles/{id}/start` | | `tasks_cycle_update` | Change a cycle | write | `tasks:write` | `PATCH /api/v1/tasks/cycles/{id}` | | `tasks_dependency_list` | List issue dependencies | read | `tasks:read` | `GET /api/v1/tasks/dependencies` | | `tasks_document_link` | Add a document to a project | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/documents` | | `tasks_document_list` | List a project's documents | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/documents` | | `tasks_document_unlink` | Remove a document from a project | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/projects/{id}/documents` | | `tasks_export_cancel` | Cancel or delete a workspace export | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/export/{id}` | | `tasks_export_create` | Start a workspace export | write | `tasks:write` | `POST /api/v1/tasks/export` | | `tasks_export_get` | Read a workspace export | read | `tasks:read` | `GET /api/v1/tasks/export/{id}` | | `tasks_export_list` | List your workspace exports | read | `tasks:read` | `GET /api/v1/tasks/export` | | `tasks_favorite_create` | Favourite something | write | `tasks:write` | `POST /api/v1/tasks/favorites` | | `tasks_favorite_delete` | Remove a favourite | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/favorites/{id}` | | `tasks_favorite_list` | List your favourites | read | `tasks:read` | `GET /api/v1/tasks/favorites` | | `tasks_favorite_update` | Move a favourite | write | `tasks:write` | `PATCH /api/v1/tasks/favorites/{id}` | | `tasks_flow_insight_get` | Read a cumulative flow | read | `tasks:read` | `GET /api/v1/tasks/insights/flow` | | `tasks_follow_list` | List what is in your Pulse | read | `tasks:read` | `GET /api/v1/tasks/pulse/follows` | | `tasks_github_get` | Read the GitHub connection | read | `tasks:read` | `GET /api/v1/tasks/github` | | `tasks_github_intent_set` | Set GitHub intent labels | write | `tasks:write` | `PUT /api/v1/tasks/github/intents` | | `tasks_github_rule_set` | Set a team's GitHub rules | write | `tasks:write` | `PUT /api/v1/tasks/github/rules` | | `tasks_github_summary_get` | Read the GitHub summary | read | `tasks:read` | `GET /api/v1/tasks/github/summary` | | `tasks_github_update` | Set GitHub automations | write | `tasks:write` | `PATCH /api/v1/tasks/github` | | `tasks_import_job_get` | Read an import | read | `tasks:read` | `GET /api/v1/tasks/import/jobs/{id}` | | `tasks_import_job_list` | List imports | read | `tasks:read` | `GET /api/v1/tasks/import/jobs` | | `tasks_import_job_update` | Pause, resume or cancel an import | write | `tasks:write` | `PATCH /api/v1/tasks/import/jobs/{id}` | | `tasks_initiative_create` | Create an initiative | write | `tasks:write` | `POST /api/v1/tasks/initiatives` | | `tasks_initiative_delete` | Delete an initiative | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/initiatives/{id}` | | `tasks_initiative_export` | Export initiatives as CSV | read | `tasks:read` | `GET /api/v1/tasks/initiatives/export` | | `tasks_initiative_follow` | Follow an initiative | write | `tasks:write` | `POST /api/v1/tasks/initiatives/{id}/follow` | | `tasks_initiative_get` | Read an initiative | read | `tasks:read` | `GET /api/v1/tasks/initiatives/{id}` | | `tasks_initiative_list` | List initiatives | read | `tasks:read` | `GET /api/v1/tasks/initiatives` | | `tasks_initiative_unfollow` | Unfollow an initiative | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/initiatives/{id}/follow` | | `tasks_initiative_update` | Change an initiative | write | `tasks:write` | `PATCH /api/v1/tasks/initiatives/{id}` | | `tasks_initiative_update_create` | Post an initiative status update | write | `tasks:write` | `POST /api/v1/tasks/initiatives/{id}/updates` | | `tasks_initiative_update_list` | List an initiative's status updates | read | `tasks:read` | `GET /api/v1/tasks/initiatives/{id}/updates` | | `tasks_initiativeupdate_delete` | Delete an initiative status update | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/initiative-updates/{id}` | | `tasks_initiativeupdate_update` | Edit an initiative status update | write | `tasks:write` | `PATCH /api/v1/tasks/initiative-updates/{id}` | | `tasks_insight_get` | Read Tasks insights | read | `tasks:read` | `GET /api/v1/tasks/insights` | | `tasks_issue_batch` | Change many issues at once | write | `tasks:write` | `POST /api/v1/tasks/issues/batch` | | `tasks_issue_claim` | Claim an issue | write | `tasks:write` | `POST /api/v1/issues/{id}/claim` | | `tasks_issue_convert_to_project` | Convert an issue to a project | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/convert-to-project` | | `tasks_issue_create` | Create an issue | write | `tasks:write` | `POST /api/v1/issues` | | `tasks_issue_delete` | Delete an issue | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/issues/{id}` | | `tasks_issue_duplicate` | Make a copy of an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/duplicate` | | `tasks_issue_export` | Export a list of issues as CSV | read | `tasks:read` | `GET /api/v1/tasks/issues/export` | | `tasks_issue_get` | Read an issue | read | `tasks:read` | `GET /api/v1/issues/{id}` | | `tasks_issue_history` | List an issue's description versions | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/history` | | `tasks_issue_list_mine` | List my issues | read | `tasks:read` | `GET /api/v1/issues/mine` | | `tasks_issue_move` | Move issues to another team | write | `tasks:write` | `POST /api/v1/tasks/issues/move` | | `tasks_issue_progress` | Report progress | write | `tasks:write` | `POST /api/v1/issues/{id}/progress` | | `tasks_issue_revert` | Restore an earlier description | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/history/{version_id}/restore` | | `tasks_issue_search` | Search issues | read | `tasks:read` | `GET /api/v1/issues` | | `tasks_issue_subscribe` | Subscribe to an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/subscribe` | | `tasks_issue_triage` | Triage an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/triage` | | `tasks_issue_unsubscribe` | Unsubscribe from an issue | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/issues/{id}/subscribe` | | `tasks_issue_update` | Update an issue | write | `tasks:write` | `PATCH /api/v1/issues/{id}` | | `tasks_label_create` | Create a label | write | `tasks:write` | `POST /api/v1/tasks/labels` | | `tasks_label_delete` | Delete a label | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/labels/{id}` | | `tasks_label_list` | List labels | read | `tasks:read` | `GET /api/v1/tasks/labels` | | `tasks_label_update` | Change a label | write | `tasks:write` | `PATCH /api/v1/tasks/labels/{id}` | | `tasks_labelgroup_create` | Create a label group | write | `tasks:write` | `POST /api/v1/tasks/label-groups` | | `tasks_labelgroup_delete` | Delete a label group | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/label-groups/{id}` | | `tasks_labelgroup_list` | List label groups | read | `tasks:read` | `GET /api/v1/tasks/label-groups` | | `tasks_labelgroup_update` | Change a label group | write | `tasks:write` | `PATCH /api/v1/tasks/label-groups/{id}` | | `tasks_link_create` | Add a link to an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/links` | | `tasks_link_delete` | Remove a link | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/links/{id}` | | `tasks_link_list` | List an issue's links | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/links` | | `tasks_link_update` | Edit a link | write | `tasks:write` | `PATCH /api/v1/tasks/links/{id}` | | `tasks_member_export` | Export members as CSV | read | `tasks:read` | `GET /api/v1/tasks/members/export` | | `tasks_member_list` | List the organisation's members | read | `tasks:read` | `GET /api/v1/tasks/members` | | `tasks_milestone_create` | Add a milestone | write | `tasks:write` | `POST /api/v1/tasks/projects/{project_id}/milestones` | | `tasks_milestone_delete` | Delete a milestone | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/milestones/{id}` | | `tasks_milestone_list` | List milestones | read | `tasks:read` | `GET /api/v1/tasks/projects/{project_id}/milestones` (+1) | | `tasks_milestone_update` | Change a milestone | write | `tasks:write` | `PATCH /api/v1/tasks/milestones/{id}` | | `tasks_note_link` | Link or create a note for an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/notes` | | `tasks_note_list` | List an issue's linked notes | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/notes` | | `tasks_note_unlink` | Unlink a note from an issue | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/issues/{id}/notes` | | `tasks_notification_channels_update` | Turn push or email off for the org | write | `tasks:write` | `PUT /api/v1/tasks/notifications/channels` | | `tasks_notification_list` | List your notifications | read | `tasks:read` | `GET /api/v1/tasks/notifications` | | `tasks_notification_read_all` | Mark every notification read | write | `tasks:write` | `POST /api/v1/tasks/notifications/read-all` | | `tasks_notification_settings_get` | Read your notification settings | read | `tasks:read` | `GET /api/v1/tasks/notifications/settings` | | `tasks_notification_settings_update` | Change your notification settings | write | `tasks:write` | `PUT /api/v1/tasks/notifications/settings` | | `tasks_notification_update` | Read, archive or snooze a notification | write | `tasks:write` | `PATCH /api/v1/tasks/notifications/{id}` | | `tasks_project_activity` | List a project's activity | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/activity` | | `tasks_project_create` | Create a project | write | `tasks:write` | `POST /api/v1/tasks/projects` | | `tasks_project_delete` | Delete a project | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/projects/{id}` | | `tasks_project_export` | Export projects as CSV | read | `tasks:read` | `GET /api/v1/tasks/projects/export` | | `tasks_project_follow` | Follow a project | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/follow` | | `tasks_project_get` | Read a project | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}` | | `tasks_project_insight_get` | Read a project's insights | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/insights` | | `tasks_project_list` | List projects | read | `tasks:read` | `GET /api/v1/tasks/projects` | | `tasks_project_move` | Move a project to another team | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/move` | | `tasks_project_unfollow` | Unfollow a project | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/projects/{id}/follow` | | `tasks_project_update` | Change a project | write | `tasks:write` | `PATCH /api/v1/tasks/projects/{id}` | | `tasks_projectdep_add` | Add a project dependency | write | `tasks:write` | `POST /api/v1/tasks/projects/{project}/dependencies` | | `tasks_projectdep_list` | List project dependencies | read | `tasks:read` | `GET /api/v1/tasks/projects/{project}/dependencies` (+1) | | `tasks_projectdep_remove` | Remove a project dependency | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/projects/{project}/dependencies` | | `tasks_projectlink_create` | Add a link to a project | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/links` | | `tasks_projectlink_list` | List a project's links | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/links` | | `tasks_projectrequest_create` | Add a customer request to a project | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/requests` | | `tasks_projectrequest_list` | List a project's customer requests | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/requests` | | `tasks_projectupdate_create` | Post a project status update | write | `tasks:write` | `POST /api/v1/tasks/projects/{id}/updates` | | `tasks_projectupdate_delete` | Delete a project status update | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/project-updates/{id}` | | `tasks_projectupdate_list` | List a project's status updates | read | `tasks:read` | `GET /api/v1/tasks/projects/{id}/updates` | | `tasks_projectupdate_update` | Edit a project status update | write | `tasks:write` | `PATCH /api/v1/tasks/project-updates/{id}` | | `tasks_pullrequest_link` | Refresh an issue's pull requests | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/pull-requests` | | `tasks_pullrequest_list` | List an issue's pull requests | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/pull-requests` | | `tasks_pullrequest_unlink` | Unlink a pull request from an issue | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/issues/{id}/pull-requests/{pr_id}` | | `tasks_pulse_digest_create` | Make last week's Pulse digest | write | `tasks:write` | `POST /api/v1/tasks/pulse/digests` | | `tasks_pulse_digest_get` | Read a Pulse digest | read | `tasks:read` | `GET /api/v1/tasks/pulse/digests/{id}` | | `tasks_pulse_digest_list` | List your weekly Pulse digests | read | `tasks:read` | `GET /api/v1/tasks/pulse/digests` | | `tasks_pulse_digest_update` | Mark a Pulse digest read | write | `tasks:write` | `PATCH /api/v1/tasks/pulse/digests/{id}` | | `tasks_pulse_get` | Read your Pulse | read | `tasks:read` | `GET /api/v1/tasks/pulse` | | `tasks_pulse_settings_get` | Read the org's Pulse settings | read | `tasks:read` | `GET /api/v1/tasks/pulse/settings` | | `tasks_pulse_settings_update` | Change the org's Pulse settings | write | `tasks:write` | `PUT /api/v1/tasks/pulse/settings` | | `tasks_reaction_add` | React with an emoji | write | `tasks:write` | `POST /api/v1/tasks/comments/{comment_id}/reactions` (+1) | | `tasks_reaction_remove` | Remove a reaction | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/comments/{comment_id}/reactions` (+1) | | `tasks_recurring_create` | Create a recurring issue | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/recurring` | | `tasks_recurring_delete` | Delete a recurring issue | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/recurring/{id}` | | `tasks_recurring_get` | Read a recurring issue | read | `tasks:read` | `GET /api/v1/tasks/recurring/{id}` | | `tasks_recurring_list` | List a team's recurring issues | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/recurring` | | `tasks_recurring_update` | Change a recurring issue | write | `tasks:write` | `PATCH /api/v1/tasks/recurring/{id}` | | `tasks_relation_create` | Relate two issues | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/relations` | | `tasks_relation_delete` | Remove an issue relation | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/relations/{id}` | | `tasks_release_complete` | Complete a release | write | `tasks:write` | `POST /api/v1/tasks/releases/{release}/complete` | | `tasks_release_create` | Create a release | write | `tasks:write` | `POST /api/v1/tasks/releases/pipelines/{pipeline}/releases` | | `tasks_release_draft` | Draft release notes | read | `tasks:read` | `GET /api/v1/tasks/releases/{release}/draft` | | `tasks_release_get` | Read a release | read | `tasks:read` | `GET /api/v1/tasks/releases/{release}` | | `tasks_release_issue_add` | Add issues to a release | write | `tasks:write` | `POST /api/v1/tasks/releases/{release}/issues` | | `tasks_release_issue_remove` | Remove issues from a release | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/releases/{release}/issues` | | `tasks_release_list` | List releases | read | `tasks:read` | `GET /api/v1/tasks/releases/pipelines/{pipeline}/releases` (+1) | | `tasks_release_update` | Change a release | write | `tasks:write` | `PATCH /api/v1/tasks/releases/{release}` | | `tasks_releaseautomation_get` | Read a team's release automation | read | `tasks:read` | `GET /api/v1/tasks/releases/automation/{team}` | | `tasks_releaseautomation_update` | Set a team's release automation | write | `tasks:write` | `PUT /api/v1/tasks/releases/automation/{team}` | | `tasks_releasechangelog_get` | Read a pipeline's changelog | read | `tasks:read` | `GET /api/v1/tasks/releases/pipelines/{pipeline}/changelog` | | `tasks_releasekey_create` | Create a pipeline CI key | write | `tasks:write` | `POST /api/v1/tasks/releases/pipelines/{pipeline}/keys` | | `tasks_releasekey_list` | List a pipeline's CI keys | read | `tasks:read` | `GET /api/v1/tasks/releases/pipelines/{pipeline}/keys` | | `tasks_releasekey_revoke` | Revoke a pipeline CI key | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/releases/pipelines/{pipeline}/keys/{key}` | | `tasks_releasepipeline_create` | Create a release pipeline | write | `tasks:write` | `POST /api/v1/tasks/releases/pipelines` | | `tasks_releasepipeline_delete` | Delete a release pipeline | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/releases/pipelines/{pipeline}` | | `tasks_releasepipeline_list` | List release pipelines | read | `tasks:read` | `GET /api/v1/tasks/releases/pipelines` | | `tasks_releasepipeline_restore` | Restore a deleted release pipeline | write | `tasks:write` | `POST /api/v1/tasks/releases/pipelines/{pipeline}/restore` | | `tasks_releasepipeline_update` | Change a release pipeline | write | `tasks:write` | `PATCH /api/v1/tasks/releases/pipelines/{pipeline}` | | `tasks_reminder_delete` | Cancel a reminder | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/reminders/{id}` | | `tasks_reminder_list` | List your reminders | read | `tasks:read` | `GET /api/v1/tasks/reminders` | | `tasks_reminder_set` | Set a reminder | write | `tasks:write` | `PUT /api/v1/tasks/reminders` | | `tasks_request_create` | Add a customer request to an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/requests` | | `tasks_request_delete` | Remove a customer request | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/requests/{id}` | | `tasks_request_list` | List an issue's customer requests | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/requests` | | `tasks_request_update` | Change a customer request's quote | write | `tasks:write` | `PATCH /api/v1/tasks/requests/{id}` | | `tasks_saved_insight_create` | Save an insight | write | `tasks:write` | `POST /api/v1/tasks/saved-insights` | | `tasks_saved_insight_delete` | Delete a saved insight | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/saved-insights/{id}` | | `tasks_saved_insight_get` | Read a saved insight | read | `tasks:read` | `GET /api/v1/tasks/saved-insights/{id}` | | `tasks_saved_insight_list` | List saved insights | read | `tasks:read` | `GET /api/v1/tasks/saved-insights` | | `tasks_saved_insight_run` | Run a saved insight | read | `tasks:read` | `GET /api/v1/tasks/saved-insights/{id}/result` | | `tasks_saved_insight_update` | Change a saved insight | write | `tasks:write` | `PATCH /api/v1/tasks/saved-insights/{id}` | | `tasks_sla_get` | Read a team's SLA rules | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/sla` | | `tasks_sla_set` | Set a team's SLA rules | write | `tasks:write` | `PUT /api/v1/tasks/teams/{id}/sla` | | `tasks_state_create` | Add a workflow state | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/states` | | `tasks_state_delete` | Delete a workflow state | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/states/{id}` | | `tasks_state_list` | List a team's workflow states | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/states` | | `tasks_state_reorder` | Reorder workflow states | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/states/reorder` | | `tasks_state_update` | Change a workflow state | write | `tasks:write` | `PATCH /api/v1/tasks/states/{id}` | | `tasks_suggestion_create` | Ask for AI suggestions | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/suggestions` | | `tasks_suggestion_decide` | Accept or dismiss a suggestion | write | `tasks:write` | `POST /api/v1/tasks/suggestions/{id}` | | `tasks_suggestion_list` | List AI suggestions for an issue | read | `tasks:read` | `GET /api/v1/tasks/issues/{id}/suggestions` | | `tasks_team_create` | Create a team | write | `tasks:write` | `POST /api/v1/tasks/teams` | | `tasks_team_delete` | Delete a team | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/teams/{id}` | | `tasks_team_list` | List teams | read | `tasks:read` | `GET /api/v1/teams` | | `tasks_team_update` | Change a team | write | `tasks:write` | `PATCH /api/v1/tasks/teams/{id}` | | `tasks_teammember_add` | Add a member to a team | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/members` | | `tasks_teammember_list` | List a team's members | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/members` | | `tasks_teammember_remove` | Remove a member from a team | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/teams/{id}/members/{member_id}` | | `tasks_template_apply` | Apply a template to an issue | write | `tasks:write` | `POST /api/v1/tasks/issues/{id}/apply-template` | | `tasks_template_create` | Create an issue template | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/templates` (+1) | | `tasks_template_delete` | Delete an issue template | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/templates/{id}` | | `tasks_template_get` | Read an issue template | read | `tasks:read` | `GET /api/v1/tasks/templates/{id}` | | `tasks_template_list` | List issue templates | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/templates` (+1) | | `tasks_template_update` | Change an issue template | write | `tasks:write` | `PATCH /api/v1/tasks/templates/{id}` | | `tasks_thread_mute` | Mute or unmute a comment thread | write | `tasks:write` | `PUT /api/v1/tasks/comments/{comment}/mute` | | `tasks_triage_get` | Read a team's AI triage settings | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/ai-triage` | | `tasks_triage_set` | Set a team's AI triage settings | write | `tasks:write` | `PUT /api/v1/tasks/teams/{id}/ai-triage` | | `tasks_triagerule_create` | Create a triage rule | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/triage-rules` | | `tasks_triagerule_delete` | Delete a triage rule | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/triage-rules/{id}` | | `tasks_triagerule_get` | Read a triage rule | read | `tasks:read` | `GET /api/v1/tasks/triage-rules/{id}` | | `tasks_triagerule_list` | List a team's triage rules | read | `tasks:read` | `GET /api/v1/tasks/teams/{id}/triage-rules` | | `tasks_triagerule_reorder` | Reorder a team's triage rules | write | `tasks:write` | `POST /api/v1/tasks/teams/{id}/triage-rules/reorder` | | `tasks_triagerule_test` | Try a triage rule | read | `tasks:read` | `POST /api/v1/tasks/teams/{id}/triage-rules/test` | | `tasks_triagerule_update` | Change a triage rule | write | `tasks:write` | `PATCH /api/v1/tasks/triage-rules/{id}` | | `tasks_updatecomment_create` | Comment on an update | write | `tasks:write` | `POST /api/v1/tasks/updates/{update_kind}/{update_id}/comments` | | `tasks_updatecomment_delete` | Delete a comment on an update | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/update-comments/{id}` | | `tasks_updatecomment_list` | List comments on an update | read | `tasks:read` | `GET /api/v1/tasks/updates/{update_kind}/{update_id}/comments` | | `tasks_updatecomment_update` | Edit a comment on an update | write | `tasks:write` | `PATCH /api/v1/tasks/update-comments/{id}` | | `tasks_updatereaction_set` | React to an update | write | `tasks:write` | `PUT /api/v1/tasks/updates/{update_kind}/{update_id}/reactions` | | `tasks_updateschedule_get` | Read update schedules | read | `tasks:read` | `GET /api/v1/tasks/update-schedules` | | `tasks_updateschedule_set` | Set an update schedule | write | `tasks:write` | `PUT /api/v1/tasks/update-schedules` | | `tasks_view_create` | Create a saved view | write | `tasks:write` | `POST /api/v1/tasks/views` | | `tasks_view_delete` | Delete a saved view | write (destructive) | `tasks:write` | `DELETE /api/v1/tasks/views/{id}` | | `tasks_view_duplicate` | Duplicate a saved view | write | `tasks:write` | `POST /api/v1/tasks/views/{id}/duplicate` | | `tasks_view_get` | Read a saved view | read | `tasks:read` | `GET /api/v1/tasks/views/{id}` | | `tasks_view_list` | List saved views | read | `tasks:read` | `GET /api/v1/tasks/views` | | `tasks_view_subscribe` | Follow a saved view | write | `tasks:write` | `POST /api/v1/tasks/views/{id}/subscription` | | `tasks_view_update` | Change a saved view | write | `tasks:write` | `PATCH /api/v1/tasks/views/{id}` | ## Related {#related} - [Venom Tasks for agents](/docs/cloud/tasks-mcp.md): connecting clients, AI triage, linked notes and troubleshooting. - [Venom Tasks API](/docs/cloud/tasks-api.md): the app's console API and its request fields, which the tools above take. - [GitHub](/docs/cloud/tasks-github.md): linking pull requests and GitHub issues as intents. - [The REST twin](/docs/developers/rest.md) and [Venom for agents](/docs/cloud/workspace-mcp.md): the shared envelope, `If-Match` and `Idempotency-Key`. - [Authentication and scopes](/docs/developers/auth.md), [Webhooks](/docs/developers/webhooks.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Venom People URL: https://cloud.usevenom.dev/docs/developers/people Description: Search, add and update the people a member knows, log interactions and draft follow-ups from code or an agent, over REST or MCP. People is personal, so every call acts for one member. Venom People is each member's own memory of the people they know: profiles, handles, interactions, context cards, circles and follow-ups. A member can share a person with a team or the whole organisation. Every action is an MCP tool and a REST route under `/api/v1/people`, and every call acts for one member and sees what that member sees. ## What you can build {#build} - **Log touches from your other tools.** After a call, a meeting or an email, find the person (`GET /api/v1/people?query=…`) and log what happened (`POST /api/v1/people/{person}/interactions`). Promises and next steps in the summary become open loops on the person's context card. - **Add people from a sign-up or a card scan.** Add a person with their handles and a first interaction (`POST /api/v1/people`), or send text, a vCard or images to capture (`POST /api/v1/people/capture`) and confirm the drafts. - **A daily follow-up digest.** Read today's follow-ups (`GET /api/v1/people/followups`), draft a message for one (`POST /api/v1/people/followups/draft`) and record it sent once the member sends it (`POST /api/v1/people/followups/{followup}/send`). Venom never sends the message. - **Warm intros.** Search who in the organisation knows someone at a company (`GET /api/v1/people/network`) and ask that colleague for an intro (`POST /api/v1/people/intros`). - **Imports.** Send a CSV, vCard, WhatsApp chat or Telegram export (`POST /api/v1/people/import`); it is read only until `confirm`. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/people`, server name `venom-people` | | Connect | `claude mcp add --transport http venom-people https://cloud.usevenom.dev/workspace/mcp/people` | | MCP tools | 135 (50 read, 85 write) | | OAuth scopes | `people:read` `people:write` | | REST twin | 136 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `people.person.created`, `people.person.updated`, `people.person.removed` | ## Authentication and scopes {#scopes} People holds personal data, so the caller must be a member: - A **personal API key** acts for its member. - An **OAuth app** acts for the member who connected it. It needs `people:read` to use People at all and `people:write` to change anything. - A **team key** has no member and is refused every People tool, in words, with `403` over REST. So is a service agent an admin scoped to other apps. Use a member's personal key instead. The member's role decides the rest. Every member, whatever their role, writes their own private people. Sharing a person, and changing people others shared, needs a role that writes in People: owner, admin or developer. Billing and viewer members read what was shared with them and keep their own private people. The caller sees exactly what the member sees: their own people in full, and people others shared with them without notes, handles, cards or interactions. A person the member cannot see answers as if it did not exist. People is not an add-on: every organisation has it. Tools that call a model (context cards, drafts, recall, image reading) go through the organisation's gear, under its daily People AI cap. ## Worked example {#example} Find the person, then log a call with them: ```bash curl "$VENOM_CLOUD/api/v1/people?query=Sarah%20Chen%20FrostCo&limit=5" \ -H "Authorization: Bearer $VENOM_API_KEY" curl -X POST "$VENOM_CLOUD/api/v1/people//interactions" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"kind": "call", "summary": "Walked through GPU pricing for the warehouse cluster. I promised a revised quote by Friday.", "occurred_at": "2026-11-09", "channel": "phone", "direction": "out"}' ``` The same call logged over MCP, from any client connected to `/workspace/mcp/people`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "people_interaction_create", "arguments": { "person": "", "kind": "call", "summary": "Walked through GPU pricing for the warehouse cluster. I promised a revised quote by Friday.", "occurred_at": "2026-11-09", "channel": "phone", "direction": "out" } } } ``` `kind` is one of `met`, `call`, `message`, `meeting`, `email` or `note`. `direction` is `in` (they reached out), `out` (you did) or `both` (the default); the strength score reads it. Person ids are UUIDs from the search. Over MCP, pass `format: "json"` for structured answers; the REST routes always answer JSON. The MCP tool also takes `place` and `globe_note` (a note id the interaction points at). The REST route does not accept them yet. ## Rules for agents {#rules} - Search before you add: `people_person_create` answers possible duplicates, and `people_person_merge` folds two people into one. - Never send a message for the member. Draft it, and record it sent only after the member sent it. - A context card refresh costs one model call under the daily cap; do not refresh in a loop. ## Events {#events} 3 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `people.person.created` | A person became visible to the whole org in Venom People (added as org-wide, or shared with the org): id, name, role, company and the member who owns the record. Never handles, notes, how you met or interactions; a private or team-only person is never sent. | | `people.person.updated` | An org-wide person in Venom People changed: the same short fields as when it was added. | | `people.person.removed` | An org-wide person is no longer visible to the org: archived, merged into another, or made private or team-only again. Its id only. | `workspace_change_list` covers notes and issues only, not People. To keep another system in step with a member's people, poll `GET /api/v1/people` and `GET /api/v1/people/followups` with that member's own key. ## REST routes {#rest} The REST twin: 136 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/people** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people` | Search or list people you know and people shared with you | `people_person_search` | | POST | `/api/v1/people` | Add a person, optionally with the first interaction | `people_person_create` | | GET | `/api/v1/people/{person}` | Read a person | `people_person_get` | | PATCH | `/api/v1/people/{person}` | Change one of your people | `people_person_update` | **/people/reach** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/reach` | Whom to reach for a topic in a territory: your own people ranked by fit, seniority and reachability, each with a route and why | `people_reach_search` | **/people/events** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/events` | List events, with how many of your people you met at each | `people_event_list` | | POST | `/api/v1/people/events` | Add a conference or meetup | `people_event_create` | **/people/controversy** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/people/controversy/setting` | Owners and admins: turn the public controversy check on or off (off deletes stored matches) | `people_controversy_set` | | GET | `/api/v1/people/controversy` | People with a possible or confirmed CancelPeople.com match | `people_controversy_list` | | GET | `/api/v1/people/{person}/controversy` | What CancelPeople.com reports about a person, summarised, with things to watch out for | `people_controversy_get` | | POST | `/api/v1/people/{person}/controversy/run` | Run the public controversy check for a person now | `people_controversy_run` | | POST | `/api/v1/people/{person}/controversy/decide` | Same person (confirmed) or Not this person (dismissed) for a possible CancelPeople.com match | `people_controversy_decide` | **/people/signals** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/signals/setting` | People signals: on or off, the gear and its model, caps, today's spend and how many people have a result | `people_signalsetting_get` | | PUT | `/api/v1/people/signals/setting` | Owners and admins: change People signals' settings | `people_signalsetting_set` | | GET | `/api/v1/people/{person}/signals` | A person's signals: the call, strengths, weaknesses and a score per indicator, or insufficient data | `people_signal_get` | | POST | `/api/v1/people/{person}/signals/run` | Assess a person now, within the caps | `people_signal_run` | **/people/ai** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/ai/setting` | People's daily AI limit and today's spend against it and each feature's own daily cap, and the gear People's AI runs on with every gear it may use | `people_aisetting_get` | | PUT | `/api/v1/people/ai/setting` | Owners and admins: change People's daily AI limit, its gear or the out-of-credit fallback | `people_aisetting_set` | **/people/classify** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/classify/setting` | People classification: on or off, focus, taxonomy, gear, caps, schedule and today's spend | `people_classifier_get` | | PUT | `/api/v1/people/classify/setting` | Owners and admins: change People classification's settings | `people_classifier_set` | | GET | `/api/v1/people/classify/runs` | The latest classification runs with their people, calls, cost and why they stopped | `people_classifier_history` | | POST | `/api/v1/people/classify/runs` | Estimate (dry_run) or start a classification run, classify one person, or continue a run | `people_classify_run` | | GET | `/api/v1/people/classify/corrections` | Your classification corrections: what the model said and what you chose | `people_correction_list` | | GET | `/api/v1/people/classify/quality` | Override rate per field over 30 days, without and with corrections as examples | `people_quality_get` | | GET | `/api/v1/people/classify/proposals` | Proposed new sector, persona and opportunity values | `people_proposal_list` | | POST | `/api/v1/people/classify/proposals` | Estimate (dry_run) or run one scan for new category values | `people_taxonomy_propose` | | POST | `/api/v1/people/classify/proposals/{proposal}/accept` | Owners and admins: add a proposed value to its list | `people_proposal_accept` | | POST | `/api/v1/people/classify/proposals/{proposal}/dismiss` | Owners and admins: dismiss a proposed value for good | `people_proposal_dismiss` | | POST | `/api/v1/people/classify/tags` | Preview (dry_run) or add tags from classifications; never removes a tag | `people_autotag_apply` | **/people/classification** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/people/{person}/classification` | Set fields of a person's classification by hand (null clears one) | `people_classification_set` | **/people/enrichment** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/enrichment/setting` | People enrichment: on or off, the providers in order (what each is sent), the daily cap and today's spend | `people_enricher_get` | | PUT | `/api/v1/people/enrichment/setting` | Owners and admins: turn enrichment on or off, pick providers in order, set the daily cap, store or remove PDL and Apollo keys | `people_enricher_set` | | POST | `/api/v1/people/enrichment/runs` | Enrich many of your people: start a run (people) or continue one (run); answers progress and cost | `people_enrichment_run` | | GET | `/api/v1/people/enrichment/next` | Your people most worth enriching next | `people_enrichment_next` | | GET | `/api/v1/people/{person}/enrichment` | A person's pending enrichment suggestions and photo candidates | `people_enrichment_get` | | DELETE | `/api/v1/people/{person}/enrichment` | Dismiss a person's pending enrichment suggestions | `people_enrichment_dismiss` | | POST | `/api/v1/people/{person}/enrichment/apply` | Apply some or all enrichment suggestions, and optionally a photo candidate | `people_enrichment_apply` | **/people/today** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/today/find` | Find your own people for a request (one bounded model exchange over the People search tools, else a word search), each with a why line | `people_today_find` | | GET | `/api/v1/people/today/settings` | Your settings for People's Today | `people_todaysetting_get` | | PUT | `/api/v1/people/today/settings` | Change your settings for People's Today | `people_todaysetting_set` | | POST | `/api/v1/people/today/notes` | Save how reaching out (or a meeting) went as an interaction with an outcome, then the next step (one bounded model call, else rules) | `people_todaynote_create` | **/people/briefs** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/briefs` | Your standing briefs and their plans | `people_brief_list` | | POST | `/api/v1/people/briefs` | Save a request as a standing brief for the day's picks | `people_brief_create` | | PATCH | `/api/v1/people/briefs/{brief}` | Change, pause or resume a standing brief | `people_brief_update` | | DELETE | `/api/v1/people/briefs/{brief}` | Delete a standing brief | `people_brief_delete` | **/people/downvotes** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/downvotes` | Your people marked not yet, with reason and date | `people_downvote_list` | | POST | `/api/v1/people/downvotes` | Mark one of your people not yet: left out of Today for some days, with a reason | `people_downvote_set` | | DELETE | `/api/v1/people/downvotes/{person}` | Undo not yet for one of your people | `people_downvote_delete` | **/people/next-steps** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/next-steps` | The next step a note proposed, by step or the newest for a person | `people_nextstep_get` | | POST | `/api/v1/people/next-steps/{step}/apply` | Apply a next step, or change its action or date | `people_nextstep_apply` | | POST | `/api/v1/people/next-steps/{step}/undo` | Undo an applied next step | `people_nextstep_undo` | **/people/overnight** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/overnight` | Your overnight queue: picks with route, why line and draft; your saved Reach views' nightly switches; last night's numbers | `people_overnight_list` | | POST | `/api/v1/people/overnight/picks/{pick}` | Act on an overnight pick: edit the draft, log it sent (once), skip, not yet, or redraft | `people_overnight_update` | | POST | `/api/v1/people/overnight/runs` | Run your nightly Reach views now, under the same limits | `people_overnight_run` | **/people/outreach** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/outreach/reservations` | Reserve one message to one of your people on one channel: every rule checked, a cap slot held for 30 minutes | `people_outreach_reserve` | | POST | `/api/v1/people/outreach/reservations/{reservation}/send` | Send a reserved message through Venom Comms as you (or hold it for approval, or draft it, as the bot's settings say) | `people_outreach_send` | | POST | `/api/v1/people/outreach/reservations/{reservation}/outcome` | Say how a send from a bot's own computer went: sent, failed or needs_owner (once) | `people_outreach_mark_sent` | | POST | `/api/v1/people/outreach/drafts` | Leave a message as a draft in your overnight queue (nothing is sent) | `people_outreach_draft` | | GET | `/api/v1/people/outreach` | What was reserved, drafted and sent, newest first | `people_outreach_list` | **/people/views** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/people/views/{view}` | Switch a saved Reach view to run every night, or off, and set how many it picks | `people_view_update` | **/people/intro-asks** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/intro-asks` | Your intro asks (and colleague requests) with state, age, drafts, nudges due, deal and send-through-Venom status | `people_introask_list` | | POST | `/api/v1/people/intro-asks` | Draft an intro ask to one of your contacts (template, no model), or drafts in bulk for up to 50 of your people, optionally on a Funnel deal | `people_introask_create` | | PATCH | `/api/v1/people/intro-asks/{ask}` | Edit, rewrite, link to a deal or record what happened to an intro ask (sent, nudged, agreed, introduced, declined, no_reply, dropped) | `people_introask_update` | | POST | `/api/v1/people/intro-asks/{ask}/send` | Send the draft ask or the due nudge to the connector through Venom Comms (one message per call, the outreach rules apply) | `people_introask_send` | | PUT | `/api/v1/people/intro-asks/settings` | Your one-line pitch for intro blurbs and the name drafts sign with | `people_introsetting_set` | **/people/meetings** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/meetings/sync` | Your Granola meetings sync: connected, on or off, tasks mode, last run and error, open review items | `people_meetingsync_get` | | PUT | `/api/v1/people/meetings/sync` | Turn your meetings sync on or off, or choose create or suggest for action items | `people_meetingsync_set` | | POST | `/api/v1/people/meetings/sync/runs` | Run your Granola meetings sync now | `people_meetingsync_run` | | GET | `/api/v1/people/meetings/history` | Your calendar accounts and where each one's import of past meetings is | `people_meetinghistory_get` | | POST | `/api/v1/people/meetings/history/runs` | Import the last 24 months of meetings from one calendar account, or from all of them | `people_meetinghistory_run` | | GET | `/api/v1/people/meetings/reviews` | The meetings review queue: attendees without an email, suggested action items, people from ended calendar meetings who are not in People | `people_meetingreview_list` | | GET | `/api/v1/people/meetings` | Your meetings from the last day and a half to a week ahead, with their people | `people_meeting_list` | | POST | `/api/v1/people/meetings/{meeting}/people` | Attach, confirm or detach a person on one of your meetings | `people_meeting_link` | | POST | `/api/v1/people/meetings/reviews/{review}` | Accept, create or dismiss one review item | `people_meetingreview_decide` | **/people/meeting-briefs** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/meeting-briefs` | The brief for a person, or for every person in one of your meetings | `people_meetingbrief_get` | | POST | `/api/v1/people/meeting-briefs/talking-points` | Three talking points for a person, each citing a fact (one model call under the AI limit) | `people_meetingbrief_draft` | **/people/note-changes** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/note-changes/{change}/apply` | Apply one change a meeting note proposed | `people_notechange_apply` | | POST | `/api/v1/people/note-changes/{change}/dismiss` | Dismiss one change a meeting note proposed | `people_notechange_dismiss` | **/people/capture** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/capture` | Draft people from text, a card photo or a vCard, or save drafts (confirm) | `people_capture_create` | **/people/bulk** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/bulk` | Change many of your people at once: tags, circle, cadence, company, location, seniority, country, gender, sector, delete to the trash or restore; it says who it skipped | `people_person_bulk_update` | **/people/share** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/share` | Share a person, several, or a whole circle with a team or the org (or take sharing back) | `people_person_share` | **/people/network** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/network` | Who knows someone at a company or topic: your people and what colleagues shared, with warm-intro paths | `people_network_search` | | GET | `/api/v1/people/network/paths/{person}` | Warm-intro paths to a person, ranked by the colleague's strength | `people_intro_path` | **/people/intros** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/intros` | Intro requests asked of you and sent by you | `people_intro_list` | | POST | `/api/v1/people/intros` | Ask the colleague who knows a shared person for an intro | `people_intro_request` | | POST | `/api/v1/people/intros/{request}` | Accept, decline, draft, withdraw or close as introduced an intro request | `people_intro_respond` | **/people/import** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/import` | Import contacts from a file's text (Google, vCard, LinkedIn, HubSpot, Pipedrive CSV, WhatsApp, Telegram); read-only until confirm | `people_import_run` | **/people/graph** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/graph` | Your network as a graph: you, your people, their companies, and the links between | `people_graph_get` | **/people/know-who** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/know-who` | Who you know at a company, from a school, in a place, or who worked in a country | `people_know_who` | **/people/employers** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/people/employers` | Record where you have worked (LinkedIn's Positions.csv) | `people_employer_set` | **/people/employments** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/people/employments/{employment}` | Remove a past employer from a person | `people_employment_delete` | | POST | `/api/v1/people/{person}/employments` | Link a person to a company with a role and dates | `people_employment_create` | **/people/trips** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/trips` | Your upcoming trips | `people_trip_list` | | POST | `/api/v1/people/trips` | Add a trip | `people_trip_create` | | DELETE | `/api/v1/people/trips/{trip}` | Delete a trip | `people_trip_delete` | **/people/attachments** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/attachments/{attachment}` | One image, file or link kept with a person | `people_attachment_get` | | PATCH | `/api/v1/people/attachments/{attachment}` | Rename an attachment or change its note | `people_attachment_update` | | DELETE | `/api/v1/people/attachments/{attachment}` | Delete an image, file or link kept with one of your people | `people_attachment_delete` | | GET | `/api/v1/people/{person}/attachments` | The images, files and links kept with a person | `people_attachment_list` | | POST | `/api/v1/people/{person}/attachments` | Keep a link or a file with one of your people: a file by upload_id (after the PUT), a public file_url, or small base64 | `people_attachment_add` | **/people/images** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/images/{image}` | An image kept with a person: name, type, size, pixel size and a short-lived download URL | `people_image_get` | | DELETE | `/api/v1/people/images/{image}` | Delete an image kept with one of your people | `people_image_delete` | | GET | `/api/v1/people/{person}/images` | The images kept with a person | `people_image_list` | | POST | `/api/v1/people/{person}/images` | Keep an image with one of your people: an upload_id (after the PUT), a public url, or small base64 | `people_image_add` | | POST | `/api/v1/people/images/uploads` | Prepare a one-time upload URL for a picture's raw bytes (an image, a photo, a card to capture or a file to attach) | `people_image_prepare` | | POST | `/api/v1/people/{person}/images/read` | Read a person's kept images into suggestions for their profile (saved only with apply all) | `people_image_read` | **/people/interactions** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/people/interactions/{interaction}` | Edit an interaction you logged | `people_interaction_update` | | DELETE | `/api/v1/people/interactions/{interaction}` | Delete an interaction you logged | `people_interaction_delete` | | GET | `/api/v1/people/{person}/interactions` | A person's interactions, newest first | `people_interaction_list` | | POST | `/api/v1/people/{person}/interactions` | Log an interaction with one of your people | `people_interaction_create` | **/people/relationships** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/people/relationships/{relationship}` | Remove a relationship between two of your people | `people_relationship_delete` | | GET | `/api/v1/people/{person}/relationships` | A person's links to other people and their companies over time | `people_relationship_list` | | POST | `/api/v1/people/{person}/relationships` | Link a person to another: knows, colleague, introduced by, reports to, family, partner, investor in, or your own label | `people_relationship_create` | **/people/companies** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/companies/{company}` | Read a company and the people there you may see | `people_company_get` | | PATCH | `/api/v1/people/companies/{company}` | Change a company | `people_company_update` | | GET | `/api/v1/people/companies` | List companies, with people there now and ever | `people_company_list` | **/people/followups** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/followups/{followup}` | Mark a follow-up done or sent, or snooze or dismiss it | `people_followup_done` | | PATCH | `/api/v1/people/followups/{followup}` | Replace a follow-up's draft text | `people_followup_update` | | POST | `/api/v1/people/followups/{followup}/snooze` | Snooze a follow-up for some days (kept as not yet, with a reason) | `people_followup_snooze` | | POST | `/api/v1/people/followups/{followup}/dismiss` | Dismiss a follow-up: not yet for some days, with a reason | `people_followup_dismiss` | | POST | `/api/v1/people/followups/{followup}/send` | Record that you sent a follow-up yourself (Venom sends nothing) | `people_followup_send` | | GET | `/api/v1/people/followups` | Today's follow-ups: the five people to reach out to, with reasons and drafts | `people_followup_list` | | POST | `/api/v1/people/followups/draft` | Draft a follow-up message with channel links (you send it), or add_only: add a person to today | `people_followup_draft` | **/people/card** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/{person}/card` | Rewrite a person's context card now | `people_card_refresh` | **/people/rating** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/{person}/rating` | Rate a person: hot, warm, later or skip | `people_person_rate` | **/people/circle** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/people/{person}/circle` | Set a person's circle and cadence | `people_person_circle_set` | **/people/merge** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/{keep}/merge` | Merge a duplicate into this person | `people_person_merge` | **/people/photo** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/{person}/photo` | A person's photo: name, type, size, pixel size and a short-lived download URL | `people_image_get` | | PUT | `/api/v1/people/{person}/photo` | Set a person's photo: an upload_id (after the PUT), a public url (or an enrichment candidate), or small base64 | `people_person_photo_set` | **/people/enrich** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/{person}/enrich` | Ask the org's enrichment providers about a person; answers suggestions with sources (nothing is saved) | `people_person_enrich` | **/people/links** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/{person}/links` | Why a person is connected to others: shared company, school, event, place, topic and more, with every reason | `people_link_list` | **/people/suggestions** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/{person}/suggestions` | Links worth adding: same company, same event, the introducer named in how you met (nothing is saved) | `people_suggestion_list` | **/people/debrief** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/debrief` | List events to debrief, show an event's cards, rate people met there | `people_debrief_run` | **/people/circles** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/people/circles` | Your circles with cadences, or one person's strength with the reasons | `people_circle_list` | | PATCH | `/api/v1/people/circles` | Change a circle's cadence, or a person's circle and cadence | `people_circle_update` | **/people/recall** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/people/recall` | Who do I know who…: an answer from your people with citations | `people_recall_ask` | ## MCP tools {#tools} 135 tools: 50 read, 85 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `people_aisetting_get` | People's AI limit, gear and today's spend | read | `people:read` | `GET /api/v1/people/ai/setting` | | `people_aisetting_set` | Change People's AI limit or gear | write | `people:write` | `PUT /api/v1/people/ai/setting` | | `people_attachment_add` | Keep a link or a file with a person | write | `people:write` | `POST /api/v1/people/{person}/attachments` | | `people_attachment_delete` | Delete an attachment | write (destructive) | `people:write` | `DELETE /api/v1/people/attachments/{attachment}` | | `people_attachment_get` | Read one attachment | read | `people:read` | `GET /api/v1/people/attachments/{attachment}` | | `people_attachment_list` | List what is kept with a person | read | `people:read` | `GET /api/v1/people/{person}/attachments` | | `people_attachment_update` | Rename an attachment or change its note | write | `people:write` | `PATCH /api/v1/people/attachments/{attachment}` | | `people_autotag_apply` | Add tags from classifications | write | `people:write` | `POST /api/v1/people/classify/tags` | | `people_brief_create` | Save a standing brief | write | `people:write` | `POST /api/v1/people/briefs` | | `people_brief_delete` | Delete a standing brief | write (destructive) | `people:write` | `DELETE /api/v1/people/briefs/{brief}` | | `people_brief_list` | List standing briefs | read | `people:read` | `GET /api/v1/people/briefs` | | `people_brief_update` | Change a standing brief | write | `people:write` | `PATCH /api/v1/people/briefs/{brief}` | | `people_capture_create` | Capture people from a note, photo or contact file | write | `people:write` | `POST /api/v1/people/capture` | | `people_card_refresh` | Refresh a context card | write | `people:write` | `POST /api/v1/people/{person}/card` | | `people_circle_list` | List circles | read | `people:read` | `GET /api/v1/people/circles` | | `people_circle_update` | Change a circle or cadence | write | `people:write` | `PATCH /api/v1/people/circles` | | `people_classification_set` | Set a person's classification by hand | write | `people:write` | `PUT /api/v1/people/{person}/classification` | | `people_classifier_get` | People classification settings | read | `people:read` | `GET /api/v1/people/classify/setting` | | `people_classifier_history` | People classification runs | read | `people:read` | `GET /api/v1/people/classify/runs` | | `people_classifier_set` | Change People classification settings | write | `people:write` | `PUT /api/v1/people/classify/setting` | | `people_classify_run` | Run People classification | write | `people:write` | `POST /api/v1/people/classify/runs` | | `people_company_get` | Read a company | read | `people:read` | `GET /api/v1/people/companies/{company}` | | `people_company_list` | List companies | read | `people:read` | `GET /api/v1/people/companies` | | `people_company_update` | Change a company | write | `people:write` | `PATCH /api/v1/people/companies/{company}` | | `people_controversy_decide` | Same person or not: decide a possible match | write | `people:write` | `POST /api/v1/people/{person}/controversy/decide` | | `people_controversy_get` | A person's public controversy result | read | `people:read` | `GET /api/v1/people/{person}/controversy` | | `people_controversy_list` | People flagged by the public controversy check | read | `people:read` | `GET /api/v1/people/controversy` | | `people_controversy_run` | Check a person now | write | `people:write` | `POST /api/v1/people/{person}/controversy/run` | | `people_controversy_set` | Turn the public controversy check on or off | write (destructive) | `people:write` | `PUT /api/v1/people/controversy/setting` | | `people_correction_list` | Your classification corrections | read | `people:read` | `GET /api/v1/people/classify/corrections` | | `people_debrief_run` | Debrief an event | write | `people:write` | `POST /api/v1/people/debrief` | | `people_downvote_delete` | Undo not yet | write (destructive) | `people:write` | `DELETE /api/v1/people/downvotes/{person}` | | `people_downvote_list` | List not-yet people | read | `people:read` | `GET /api/v1/people/downvotes` | | `people_downvote_set` | Mark a person not yet | write | `people:write` | `POST /api/v1/people/downvotes` | | `people_employer_set` | Record your own employers | write | `people:write` | `PUT /api/v1/people/employers` | | `people_employment_create` | Link a person to a company | write | `people:write` | `POST /api/v1/people/{person}/employments` | | `people_employment_delete` | Remove a person's past employer | write (destructive) | `people:write` | `DELETE /api/v1/people/employments/{employment}` | | `people_enricher_get` | People enrichment settings | read | `people:read` | `GET /api/v1/people/enrichment/setting` | | `people_enricher_set` | Change People enrichment settings | write | `people:write` | `PUT /api/v1/people/enrichment/setting` | | `people_enrichment_apply` | Apply enrichment suggestions | write | `people:write` | `POST /api/v1/people/{person}/enrichment/apply` | | `people_enrichment_dismiss` | Dismiss enrichment suggestions | write (destructive) | `people:write` | `DELETE /api/v1/people/{person}/enrichment` | | `people_enrichment_get` | A person's enrichment suggestions | read | `people:read` | `GET /api/v1/people/{person}/enrichment` | | `people_enrichment_next` | Who to enrich next | read | `people:read` | `GET /api/v1/people/enrichment/next` | | `people_enrichment_run` | Enrich many people | write | `people:write` | `POST /api/v1/people/enrichment/runs` | | `people_event_create` | Add an event | write | `people:write` | `POST /api/v1/people/events` | | `people_event_list` | List events | read | `people:read` | `GET /api/v1/people/events` | | `people_followup_dismiss` | Dismiss a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}/dismiss` | | `people_followup_done` | Finish, snooze or drop a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}` | | `people_followup_draft` | Draft a follow-up | write | `people:write` | `POST /api/v1/people/followups/draft` | | `people_followup_list` | Today's follow-ups | read | `people:read` | `GET /api/v1/people/followups` | | `people_followup_send` | Record a follow-up as sent | write | `people:write` | `POST /api/v1/people/followups/{followup}/send` | | `people_followup_snooze` | Snooze a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}/snooze` | | `people_followup_update` | Edit a follow-up's draft | write | `people:write` | `PATCH /api/v1/people/followups/{followup}` | | `people_graph_get` | Your network as a graph | read | `people:read` | `GET /api/v1/people/graph` | | `people_image_add` | Keep an image with a person | write | `people:write` | `POST /api/v1/people/{person}/images` | | `people_image_delete` | Delete a person's image | write (destructive) | `people:write` | `DELETE /api/v1/people/images/{image}` | | `people_image_get` | See a person's image or photo | read | `people:read` | `GET /api/v1/people/images/{image}` (+1) | | `people_image_list` | List a person's images | read | `people:read` | `GET /api/v1/people/{person}/images` | | `people_image_prepare` | Prepare a picture upload | write | `people:write` | `POST /api/v1/people/images/uploads` | | `people_image_read` | Read a person's images into their profile | write | `people:write` | `POST /api/v1/people/{person}/images/read` | | `people_import_run` | Import contacts from a file's text | write | `people:write` | `POST /api/v1/people/import` | | `people_interaction_create` | Log an interaction | write | `people:write` | `POST /api/v1/people/{person}/interactions` | | `people_interaction_delete` | Delete an interaction | write (destructive) | `people:write` | `DELETE /api/v1/people/interactions/{interaction}` | | `people_interaction_list` | List interactions | read | `people:read` | `GET /api/v1/people/{person}/interactions` | | `people_interaction_update` | Edit an interaction | write | `people:write` | `PATCH /api/v1/people/interactions/{interaction}` | | `people_intro_list` | Intro requests | read | `people:read` | `GET /api/v1/people/intros` | | `people_intro_path` | Warm-intro paths to a person | read | `people:read` | `GET /api/v1/people/network/paths/{person}` | | `people_intro_request` | Ask a colleague for an intro | write | `people:write` | `POST /api/v1/people/intros` | | `people_intro_respond` | Answer an intro request | write | `people:write` | `POST /api/v1/people/intros/{request}` | | `people_introask_create` | Draft an intro ask | write | `people:write` | `POST /api/v1/people/intro-asks` | | `people_introask_list` | List your intro asks | read | `people:read` | `GET /api/v1/people/intro-asks` | | `people_introask_send` | Send an intro ask or nudge through Venom | write (destructive) | `people:write` | `POST /api/v1/people/intro-asks/{ask}/send` | | `people_introask_update` | Change or move an intro ask | write | `people:write` | `PATCH /api/v1/people/intro-asks/{ask}` | | `people_introsetting_set` | Set your pitch for intro blurbs | write | `people:write` | `PUT /api/v1/people/intro-asks/settings` | | `people_know_who` | Who do I know at, from or in | read | `people:read` | `GET /api/v1/people/know-who` | | `people_link_list` | Why people are connected | read | `people:read` | `GET /api/v1/people/{person}/links` | | `people_meeting_link` | Change who is in a meeting | write | `people:write` | `POST /api/v1/people/meetings/{meeting}/people` | | `people_meeting_list` | List your meetings | read | `people:read` | `GET /api/v1/people/meetings` | | `people_meetingbrief_draft` | Suggest talking points | read | `people:read` | `POST /api/v1/people/meeting-briefs/talking-points` | | `people_meetingbrief_get` | Brief before a meeting | read | `people:read` | `GET /api/v1/people/meeting-briefs` | | `people_meetinghistory_get` | Past meetings import status | read | `people:read` | `GET /api/v1/people/meetings/history` | | `people_meetinghistory_run` | Import past meetings | write | `people:write` | `POST /api/v1/people/meetings/history/runs` | | `people_meetingreview_decide` | Decide a review item | write | `people:write` | `POST /api/v1/people/meetings/reviews/{review}` | | `people_meetingreview_list` | Meetings review queue | read | `people:read` | `GET /api/v1/people/meetings/reviews` | | `people_meetingsync_get` | Meetings sync status | read | `people:read` | `GET /api/v1/people/meetings/sync` | | `people_meetingsync_run` | Sync meetings now | write | `people:write` | `POST /api/v1/people/meetings/sync/runs` | | `people_meetingsync_set` | Change the meetings sync | write | `people:write` | `PUT /api/v1/people/meetings/sync` | | `people_network_search` | Who knows someone at … | read | `people:read` | `GET /api/v1/people/network` | | `people_nextstep_apply` | Apply a next step | write | `people:write` | `POST /api/v1/people/next-steps/{step}/apply` | | `people_nextstep_get` | Next step for a person | read | `people:read` | `GET /api/v1/people/next-steps` | | `people_nextstep_undo` | Undo a next step | write (destructive) | `people:write` | `POST /api/v1/people/next-steps/{step}/undo` | | `people_notechange_apply` | Apply a change from a meeting note | write | `people:write` | `POST /api/v1/people/note-changes/{change}/apply` | | `people_notechange_dismiss` | Dismiss a change from a meeting note | write | `people:write` | `POST /api/v1/people/note-changes/{change}/dismiss` | | `people_outreach_draft` | Leave a message as a draft | write | `people:write` | `POST /api/v1/people/outreach/drafts` | | `people_outreach_list` | What was reserved, drafted and sent | read | `people:read` | `GET /api/v1/people/outreach` | | `people_outreach_mark_sent` | Say how a computer send went | write | `people:write` | `POST /api/v1/people/outreach/reservations/{reservation}/outcome` | | `people_outreach_reserve` | Reserve a message to someone | write | `people:write` | `POST /api/v1/people/outreach/reservations` | | `people_outreach_send` | Send a reserved message | write (destructive) | `people:write` | `POST /api/v1/people/outreach/reservations/{reservation}/send` | | `people_overnight_list` | The overnight queue | read | `people:read` | `GET /api/v1/people/overnight` | | `people_overnight_run` | Run my night now | write | `people:write` | `POST /api/v1/people/overnight/runs` | | `people_overnight_update` | Act on an overnight pick | write | `people:write` | `POST /api/v1/people/overnight/picks/{pick}` | | `people_person_bulk_update` | Change many people at once | write (destructive) | `people:write` | `POST /api/v1/people/bulk` | | `people_person_circle_set` | Set a person's circle | write | `people:write` | `PUT /api/v1/people/{person}/circle` | | `people_person_create` | Add a person | write | `people:write` | `POST /api/v1/people` | | `people_person_enrich` | Enrich a person | write | `people:write` | `POST /api/v1/people/{person}/enrich` | | `people_person_get` | Read a person | read | `people:read` | `GET /api/v1/people/{person}` | | `people_person_merge` | Merge two people | write (destructive) | `people:write` | `POST /api/v1/people/{keep}/merge` | | `people_person_photo_set` | Set a person's photo | write | `people:write` | `PUT /api/v1/people/{person}/photo` | | `people_person_rate` | Rate a person | write | `people:write` | `POST /api/v1/people/{person}/rating` | | `people_person_search` | Search people | read | `people:read` | `GET /api/v1/people` | | `people_person_share` | Share people with a team or the org | write | `people:write` | `POST /api/v1/people/share` | | `people_person_update` | Change a person | write | `people:write` | `PATCH /api/v1/people/{person}` | | `people_proposal_accept` | Accept a proposed category | write | `people:write` | `POST /api/v1/people/classify/proposals/{proposal}/accept` | | `people_proposal_dismiss` | Dismiss a proposed category | write | `people:write` | `POST /api/v1/people/classify/proposals/{proposal}/dismiss` | | `people_proposal_list` | Proposed classification categories | read | `people:read` | `GET /api/v1/people/classify/proposals` | | `people_quality_get` | People classification quality | read | `people:read` | `GET /api/v1/people/classify/quality` | | `people_reach_search` | Whom to reach for a topic | read | `people:read` | `GET /api/v1/people/reach` | | `people_recall_ask` | Who do I know who… | read | `people:read` | `POST /api/v1/people/recall` | | `people_relationship_create` | Link two people | write | `people:write` | `POST /api/v1/people/{person}/relationships` | | `people_relationship_delete` | Remove a relationship | write (destructive) | `people:write` | `DELETE /api/v1/people/relationships/{relationship}` | | `people_relationship_list` | List a person's links | read | `people:read` | `GET /api/v1/people/{person}/relationships` | | `people_signal_get` | A person's signals | read | `people:read` | `GET /api/v1/people/{person}/signals` | | `people_signal_run` | Assess a person now | write | `people:write` | `POST /api/v1/people/{person}/signals/run` | | `people_signalsetting_get` | People signals settings | read | `people:read` | `GET /api/v1/people/signals/setting` | | `people_signalsetting_set` | Change People signals settings | write | `people:write` | `PUT /api/v1/people/signals/setting` | | `people_suggestion_list` | Suggest links | read | `people:read` | `GET /api/v1/people/{person}/suggestions` | | `people_taxonomy_propose` | Look for new classification categories | write | `people:write` | `POST /api/v1/people/classify/proposals` | | `people_today_find` | Find people to reach out to | read | `people:read` | `POST /api/v1/people/today/find` | | `people_todaynote_create` | Save how it went | write | `people:write` | `POST /api/v1/people/today/notes` | | `people_todaysetting_get` | Today settings | read | `people:read` | `GET /api/v1/people/today/settings` | | `people_todaysetting_set` | Change Today settings | write | `people:write` | `PUT /api/v1/people/today/settings` | | `people_trip_create` | Add a trip | write | `people:write` | `POST /api/v1/people/trips` | | `people_trip_delete` | Delete a trip | write (destructive) | `people:write` | `DELETE /api/v1/people/trips/{trip}` | | `people_trip_list` | List upcoming trips | read | `people:read` | `GET /api/v1/people/trips` | | `people_view_update` | Switch a Reach view to nightly | write | `people:write` | `PATCH /api/v1/people/views/{view}` | ## Related {#related} - [Venom People for agents](/docs/cloud/people-mcp.md): what each tool does, in one table. - [Venom People](/docs/cloud/people.md): who sees what, circles and the AI limits. - [Capture](/docs/cloud/people-capture.md), [Import](/docs/cloud/people-import.md), [Keep your network warm](/docs/cloud/people-keep-warm.md) and [The network](/docs/cloud/people-network.md). - [The REST twin](/docs/developers/rest.md) and [Venom for agents](/docs/cloud/workspace-mcp.md): the shared envelope and errors. - [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Venom Funnel and Outreach URL: https://cloud.usevenom.dev/docs/developers/funnel Description: Work with deals, pipelines, products, goals, reports and Outreach sequences from code or an agent, over REST or MCP, as the member whose People the deals link. Venom Funnel is the deal pipeline built on Venom People: the people on a deal are People, and what you log on a deal lands on your own people as interactions. Outreach, the follow-up sequences, lives inside Funnel. Everything an agent needs from the board, the deal page, Settings and Reports is an MCP tool on `/workspace/mcp/funnel` and a REST route under `/api/v1/funnel`. Outreach also has its own REST API under `/v1/outreach`. ## What you can build {#build} - **Deals from your sign-up or billing system.** Open a deal for a new account with `POST /api/v1/funnel/deals` (or `funnel_deal_create`), linking the people you already have in People, and move it with `POST /api/v1/funnel/deals/{deal}/move` when the account converts. - **A call logger.** After a call, log it on the deal and add a to-do with one `PATCH /api/v1/funnel/deals/{deal}` (`log` and `todo`). The to-do is a Venom Tasks issue linked to the deal. - **Forecast and goal reports.** Read the weighted forecast, win rate, velocity or lost reasons with `GET /api/v1/funnel/reports` and goal attainment with `GET /api/v1/funnel/goals` into your own dashboard. - **Quotes from your catalogue.** Keep products in sync with `funnel_product_save` and add product lines to a deal with `POST /api/v1/funnel/deals/{deal}/items`; the deal's value becomes their sum. - **Event follow-ups.** After a conference, list the people met there with `funnel_outreach_event_preview` and enroll them in a sequence with `funnel_outreach_person_enroll` (`consent_basis: met_in_person`, `dry_run` first). - **A deal assistant.** Connect `venom-funnel` and let an agent find stale deals with `funnel_deal_list`, read one with `funnel_deal_get` and prepare the next step for the member to review. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/funnel`, server name `venom-funnel` | | Connect | `claude mcp add --transport http venom-funnel https://cloud.usevenom.dev/workspace/mcp/funnel` | | MCP tools | 38 (14 read, 24 write) | | OAuth scopes | `funnel:read` `funnel:write`; `people:read` and `people:write` also open these tools | | REST twin | 42 routes under `https://cloud.usevenom.dev/api/v1` | | Outreach API | 13 operations | | Webhook events | `funnel.deal.created`, `funnel.deal.updated`, `funnel.deal.stage_changed`, `funnel.deal.archived` | ## Authentication and scopes {#scopes} A deal links the member's own People, so Funnel always acts as one member, the same caller as People: - A **personal API key** (`vck_…` with a member) acts as that member. Every org role can read and change deals today (Funnel's row in the role matrix is held at write for billing and viewer too). A key marked read-only reads only. - A **team key** has no member and is refused on every Funnel tool and `/api/v1/funnel` route, with a message that says so. The Outreach API under `/v1/outreach` is the exception: there a team key acts for the org (below). - An **OAuth app** needs `funnel:read` to use the tools and `funnel:write` to change anything. Grants made with `people:read` and `people:write` before Funnel had its own scopes still open Funnel's tools. - A **service agent** that an admin scoped to some apps reaches Funnel only when People is one of them, because Funnel runs as the People caller. The caller sees what the member sees: deals with `visibility: team` only when they are in that team, and on each deal only the people they may see. A hidden contact shows as a count. There is no Funnel add-on: every member of an organisation has it. A `todo` creates a Tasks issue, so it needs the Tasks add-on. A refused change answers `403` over REST, or a tool error that names `funnel:write` over MCP. Outreach adds one rule: **an API key or an agent counts as an agent for approval.** `funnel_outreach_run_approve` and `POST /v1/outreach/runs/{id}/approve` are refused unless the sequence sends without approval; a person approves the draft in Funnel. ## Worked example {#example} Open a deal for a person you found with `people_person_search`, log the first call with a follow-up to-do, then move the deal on: ```bash curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"title": "Example Co · GPU cluster", "value": 250000, "currency": "USD", "stage": "Qualified", "company": "Example Co", "expected_close": "2026-12-15", "people": [{"person": "0b7c6f0e-5a3e-4c0f-9a52-3a8f1d2c4b11", "role": "champion"}]}' curl -X PATCH "$VENOM_CLOUD/api/v1/funnel/deals/" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"log": {"kind": "call", "summary": "Intro call. They want a quote for 8 nodes."}, "todo": {"title": "Send the 8-node quote", "due": "2026-11-16"}}' curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals//move" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"stage": "Proposal"}' ``` The same move over MCP, from any client connected to `/workspace/mcp/funnel`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "funnel_deal_move", "arguments": { "deal": "", "stage": "Proposal", "format": "json" } } } ``` `stage` is a stage's name or id. Moving into a won or lost stage closes the deal; pass `lost_reason` for a lost one. Every move is kept in the deal's stage history. ## Values, formats and behaviour {#behaviour} - **Money.** Values in arguments are in major units (`12500.50`): `value`, a product's `price`, a line's `price` and a `won_value` goal's `target`. JSON answers carry `valueMinor` in minor units (cents). - **Answers.** Tools answer short markdown; pass `format: "json"` for `structuredContent`. The REST twin always answers JSON. - **Deal ids.** `deal` is the deal's id (a UUID). Pipelines, stages, products and fields also take a name (or a SKU for a product). - **Deal value and product lines.** While a deal has product lines, its `value` is their sum and a `value` you send is ignored. - **Setup tools.** Pipelines, stages, products, custom fields and goals change with the same checks as Settings: a new pipeline needs a won and a lost stage; a stage's `kind` changes only while it holds no deals; archiving a stage moves its deals to `move_to`; the default pipeline, or one with open deals, cannot be archived. A goal `target` of 0 or null removes the goal. - **Reports.** `report` is `summary` (default), `conversion`, `win_rate`, `velocity`, `forecast`, `team` or `lost_reasons`; `range` is `30d`, `90d`, `12m` or `ytd`. - **Retries.** No Funnel tool takes an idempotency key, so a retried `POST /api/v1/funnel/deals` can open a second deal. Look the deal up with `funnel_deal_list` (`query`) before you retry a create. ## Outreach {#outreach} Outreach tools are part of Funnel (`funnel_outreach_*`, same endpoint and scopes). They list and read your sequences and those shared with your teams, save yours, enroll People with a consent basis, pause, resume or stop an enrollment, list a sequence's enrollments (`funnel_outreach_enrollment_list`), list the queue of drafts to approve or steps to send yourself, approve or skip a step, mark a tap-to-send step sent (`funnel_outreach_run_mark_sent`), and preview one step's draft for one person. `funnel_outreach_person_enroll` with `dry_run` enrolls nobody and lists who would be skipped and why (`not_found`, `already_enrolled`, `opted_out`, `no_consent`, `no_address`). Catch-ups use `funnel_outreach_catchup_get` and `funnel_outreach_catchup_set` (`default`, `reminder` or a catch-up sequence id). Two arguments exist only on the MCP tools, not on their `/api/v1` twins: `team` on `funnel_outreach_sequence_save` (share a sequence with a team) and `sender` on `funnel_outreach_person_enroll` (send your enrollments from your own Comms senders). Use MCP, or the Outreach API below, when you need them. ### The Outreach API {#outreach-api} `/v1/outreach` is Outreach's own REST API, with an org API key like the rest of `/v1`. A member's personal key acts as that member. A **team key acts for the org**: it lists every sequence, and a sequence it creates is owned by the key. The OpenAPI document is `services/nodejs-cloud/contracts/outreach-openapi.yaml`; the docs build lists its operations in the REST section of this page. | Route | What | |---|---| | `GET`, `POST /v1/outreach/sequences` | list sequences, create one (`teamId` shares it with a team) | | `GET`, `PUT`, `DELETE /v1/outreach/sequences/{id}` | read, replace or archive one (archiving stops every live enrollment) | | `GET /v1/outreach/enrollments?sequence_id=`, `POST /v1/outreach/enrollments` | list a sequence's enrollments; enroll people (`sequenceId`, `personIds`, `dealId`, `consentBasis`, `sender`) | | `POST /v1/outreach/enrollments/{id}` | pause, resume or stop one enrollment (`action`) | | `GET /v1/outreach/queue?kind=approval` or `kind=manual` | drafts to approve, or steps to send yourself | | `POST /v1/outreach/runs/{id}/approve`, `/skip`, `/tapped` | approve a draft (optionally with an edited `subject` or `body`), skip a step, mark a tap-to-send step sent | Its fields are camelCase, as in `contracts/outreach-v1.schema.json` (TypeScript types in `contracts/outreach.ts`, examples in `contracts/fixtures/outreach`). Every route is in the [cloud API reference](/docs/api/cloud). ## Rules for agents {#agent-rules} - Search People first (`people_person_search`), then link the person with `funnel_deal_create` or `funnel_deal_update`. - Move a deal when the situation changes and log what happened with `log`: the forecast and the people's context cards depend on both. - A hidden contact shows as a count. Do not try to find out who it is. - Never contact anyone on the user's behalf. Draft, and let the user approve or send. ## Events {#events} 4 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `funnel.deal.created` | A deal visible to the whole org was created in Venom Funnel: id, title, value, currency, pipeline, stage, status, owner and company. Never its notes or the people on it; a team-only deal is never sent. | | `funnel.deal.updated` | An org-wide deal's own fields changed (title, value, owner, company, expected close), or a team deal was opened to the org: the deal as it is now. A deal moved from the org to a team sends its id and visibility only. | | `funnel.deal.stage_changed` | An org-wide deal moved to another stage: the stage before and after, its status (open, won or lost) as it is now, and who moved it. | | `funnel.deal.archived` | An org-wide deal was archived: its id and title. | Funnel and Outreach send no org webhook events. To follow changes, read deals with `funnel_deal_list` (sort and filter by stage, status or owner) or a deal's history with `funnel_deal_get`. ## REST routes {#rest} The REST twin: 42 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/funnel/pipelines** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/pipelines` | List pipelines with their stages | `funnel_pipeline_list` | | POST | `/api/v1/funnel/pipelines` | Make a pipeline with its stages | `funnel_pipeline_create` | | GET | `/api/v1/funnel/pipelines/{pipeline}` | Read a pipeline with the count and value of its deals per stage | `funnel_pipeline_get` | | PATCH | `/api/v1/funnel/pipelines/{pipeline}` | Rename a pipeline or make it the default | `funnel_pipeline_update` | | DELETE | `/api/v1/funnel/pipelines/{pipeline}` | Archive a pipeline (no open deals, not the default) | `funnel_pipeline_archive` | | POST | `/api/v1/funnel/pipelines/{pipeline}/stages` | Add a stage to a pipeline | `funnel_stage_create` | | PUT | `/api/v1/funnel/pipelines/{pipeline}/stages` | Put a pipeline's stages in this order | `funnel_stage_update` | **/funnel/reports** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/reports` | Conversion, win rate, velocity, the weighted forecast and the team | `funnel_report_get` | **/funnel/goals** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/goals` | Sales goals with attainment and pace | `funnel_goal_list` | | PUT | `/api/v1/funnel/goals` | Set a sales goal (target 0 or null removes it), or change one by its goal id | `funnel_goal_set` | **/funnel/deals** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/deals` | List deals you may see | `funnel_deal_list` | | POST | `/api/v1/funnel/deals` | Open a deal | `funnel_deal_create` | | GET | `/api/v1/funnel/deals/{deal}` | Read a deal with its people, lines, history, activity and to-dos | `funnel_deal_get` | | PATCH | `/api/v1/funnel/deals/{deal}` | Change a deal, log an activity, add a to-do | `funnel_deal_update` | | POST | `/api/v1/funnel/deals/{deal}/move` | Move a deal to a stage | `funnel_deal_move` | | POST | `/api/v1/funnel/deals/{deal}/items` | Add a product line to a deal | `funnel_item_create` | | PATCH | `/api/v1/funnel/deals/{deal}/items/{item}` | Change a line of a deal | `funnel_item_update` | | DELETE | `/api/v1/funnel/deals/{deal}/items/{item}` | Remove a line from a deal | `funnel_item_delete` | **/funnel/stages** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/funnel/stages/{stage}` | Rename a stage or change its probability, type or stale-after days | `funnel_stage_update` | | DELETE | `/api/v1/funnel/stages/{stage}` | Archive a stage, moving its deals to move_to | `funnel_stage_archive` | **/funnel/products** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/products` | The product catalogue | `funnel_product_list` | | POST | `/api/v1/funnel/products` | Add a product | `funnel_product_save` | | PATCH | `/api/v1/funnel/products/{product}` | Change, archive or restore a product | `funnel_product_save` | **/funnel/outreach** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/outreach/sequences` | Your outreach sequences with their steps and counts | `funnel_outreach_sequence_list` | | POST | `/api/v1/funnel/outreach/sequences` | Create an outreach sequence | `funnel_outreach_sequence_save` | | GET | `/api/v1/funnel/outreach/sequences/{sequence}` | Read an outreach sequence | `funnel_outreach_sequence_get` | | PUT | `/api/v1/funnel/outreach/sequences/{sequence}` | Replace one of your outreach sequences | `funnel_outreach_sequence_save` | | POST | `/api/v1/funnel/outreach/enrollments` | Enroll People in an outreach sequence | `funnel_outreach_person_enroll` | | POST | `/api/v1/funnel/outreach/enrollments/{enrollment}` | Pause, resume or stop an enrollment | `funnel_outreach_enrollment_set` | | GET | `/api/v1/funnel/outreach/queue` | Drafts to approve or steps to send by hand | `funnel_outreach_queue_list` | | POST | `/api/v1/funnel/outreach/runs/{run}/approve` | Approve an outreach draft | `funnel_outreach_run_approve` | | GET | `/api/v1/funnel/outreach/sequences/{sequence}/enrollments` | A sequence's enrollments: who is in it, at which step, and why one stopped | `funnel_outreach_enrollment_list` | | POST | `/api/v1/funnel/outreach/runs/{run}/mark-sent` | Record that you sent a tap-to-send step yourself (Venom sends nothing); the enrollment moves on | `funnel_outreach_run_mark_sent` | | POST | `/api/v1/funnel/outreach/runs/{run}/skip` | Skip an outreach step | `funnel_outreach_run_skip` | | POST | `/api/v1/funnel/outreach/runs/{run}/hold` | Hold a timed draft so it never sends by itself | `funnel_outreach_run_hold` | | POST | `/api/v1/funnel/outreach/sequences/{sequence}/preview` | Preview a step's draft for one person | `funnel_outreach_draft_preview` | | GET | `/api/v1/funnel/outreach/catchups/{person}` | What a person's keep-warm cadence runs when it comes due | `funnel_outreach_catchup_get` | | PUT | `/api/v1/funnel/outreach/catchups/{person}` | Set a person's catch-up: default, reminder or a catch-up sequence | `funnel_outreach_catchup_set` | | GET | `/api/v1/funnel/outreach/events/{event}` | The people met at an event, ready to enroll | `funnel_outreach_event_preview` | **/funnel/fields** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/funnel/fields` | The org's custom deal fields | `funnel_field_list` | | POST | `/api/v1/funnel/fields` | Add a custom deal field | `funnel_field_save` | | PATCH | `/api/v1/funnel/fields/{field}` | Change, archive or restore a custom field | `funnel_field_save` | Also the Outreach API: 13 operations, generated from `services/nodejs-cloud/contracts/outreach-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/v1/outreach/sequences` | List sequences (yours and those shared with your teams; a team key sees every one) | key or token | | POST | `/v1/outreach/sequences` | Create a sequence (status draft unless given; approval every unless given) | key or token | | GET | `/v1/outreach/sequences/{id}` | Read a sequence | key or token | | PUT | `/v1/outreach/sequences/{id}` | Replace one of your sequences (steps replace its steps in order) | key or token | | DELETE | `/v1/outreach/sequences/{id}` | Archive one of your sequences; everyone still in it stops | key or token | | GET | `/v1/outreach/enrollments` | A sequence's enrollments, newest first (in a sequence shared with your team, only your own) | key or token | | POST | `/v1/outreach/enrollments` | Enroll People in a sequence, with the consent basis for contacting them | key or token | | POST | `/v1/outreach/enrollments/{id}` | Pause, resume or stop one of your enrollments | key or token | | GET | `/v1/outreach/queue` | What waits on you, oldest first (drafts to approve, or steps to send yourself) | key or token | | POST | `/v1/outreach/runs/{id}/approve` | Approve a draft, optionally edited; it goes out inside the send window | key or token | | POST | `/v1/outreach/runs/{id}/skip` | Skip a step; the enrollment moves on to the next | key or token | | POST | `/v1/outreach/runs/{id}/hold` | Hold a draft so it never sends by itself (a timed sequence's timer is removed); it waits for a person | key or token | | POST | `/v1/outreach/runs/{id}/tapped` | Record that you sent a tap-to-send step (or did a task) yourself | key or token | ## MCP tools {#tools} 38 tools: 14 read, 24 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `funnel_deal_create` | Create a deal | write | `funnel:write` | `POST /api/v1/funnel/deals` | | `funnel_deal_get` | Read a deal | read | `funnel:read` | `GET /api/v1/funnel/deals/{deal}` | | `funnel_deal_list` | List deals | read | `funnel:read` | `GET /api/v1/funnel/deals` | | `funnel_deal_move` | Move a deal to a stage | write | `funnel:write` | `POST /api/v1/funnel/deals/{deal}/move` | | `funnel_deal_update` | Change a deal | write | `funnel:write` | `PATCH /api/v1/funnel/deals/{deal}` | | `funnel_field_list` | List custom fields | read | `funnel:read` | `GET /api/v1/funnel/fields` | | `funnel_field_save` | Add or change a custom field | write | `funnel:write` | `POST /api/v1/funnel/fields` (+1) | | `funnel_goal_list` | List sales goals | read | `funnel:read` | `GET /api/v1/funnel/goals` | | `funnel_goal_set` | Set or remove a sales goal | write | `funnel:write` | `PUT /api/v1/funnel/goals` | | `funnel_item_create` | Add a line to a deal | write | `funnel:write` | `POST /api/v1/funnel/deals/{deal}/items` | | `funnel_item_delete` | Remove a line from a deal | write (destructive) | `funnel:write` | `DELETE /api/v1/funnel/deals/{deal}/items/{item}` | | `funnel_item_update` | Change a line of a deal | write | `funnel:write` | `PATCH /api/v1/funnel/deals/{deal}/items/{item}` | | `funnel_outreach_catchup_get` | Read a person's catch-up setting | read | `funnel:read` | `GET /api/v1/funnel/outreach/catchups/{person}` | | `funnel_outreach_catchup_set` | Set a person's catch-up sequence | write | `funnel:write` | `PUT /api/v1/funnel/outreach/catchups/{person}` | | `funnel_outreach_draft_preview` | Preview an outreach draft | write | `funnel:write` | `POST /api/v1/funnel/outreach/sequences/{sequence}/preview` | | `funnel_outreach_enrollment_list` | List a sequence's enrollments | read | `funnel:read` | `GET /api/v1/funnel/outreach/sequences/{sequence}/enrollments` | | `funnel_outreach_enrollment_set` | Pause, resume or stop an enrollment | write | `funnel:write` | `POST /api/v1/funnel/outreach/enrollments/{enrollment}` | | `funnel_outreach_event_preview` | Preview an event follow-up | read | `funnel:read` | `GET /api/v1/funnel/outreach/events/{event}` | | `funnel_outreach_person_enroll` | Enroll people in a sequence | write | `funnel:write` | `POST /api/v1/funnel/outreach/enrollments` | | `funnel_outreach_queue_list` | List the outreach queue | read | `funnel:read` | `GET /api/v1/funnel/outreach/queue` | | `funnel_outreach_run_approve` | Approve an outreach draft | write | `funnel:write` | `POST /api/v1/funnel/outreach/runs/{run}/approve` | | `funnel_outreach_run_hold` | Hold an outreach draft | write | `funnel:write` | `POST /api/v1/funnel/outreach/runs/{run}/hold` | | `funnel_outreach_run_mark_sent` | Mark a tap-to-send step sent | write | `funnel:write` | `POST /api/v1/funnel/outreach/runs/{run}/mark-sent` | | `funnel_outreach_run_skip` | Skip an outreach step | write | `funnel:write` | `POST /api/v1/funnel/outreach/runs/{run}/skip` | | `funnel_outreach_sequence_get` | Read an outreach sequence | read | `funnel:read` | `GET /api/v1/funnel/outreach/sequences/{sequence}` | | `funnel_outreach_sequence_list` | List outreach sequences | read | `funnel:read` | `GET /api/v1/funnel/outreach/sequences` | | `funnel_outreach_sequence_save` | Create or change an outreach sequence | write | `funnel:write` | `POST /api/v1/funnel/outreach/sequences` (+1) | | `funnel_pipeline_archive` | Archive a pipeline | write (destructive) | `funnel:write` | `DELETE /api/v1/funnel/pipelines/{pipeline}` | | `funnel_pipeline_create` | Create a pipeline | write | `funnel:write` | `POST /api/v1/funnel/pipelines` | | `funnel_pipeline_get` | Read a pipeline | read | `funnel:read` | `GET /api/v1/funnel/pipelines/{pipeline}` | | `funnel_pipeline_list` | List pipelines | read | `funnel:read` | `GET /api/v1/funnel/pipelines` | | `funnel_pipeline_update` | Rename a pipeline | write | `funnel:write` | `PATCH /api/v1/funnel/pipelines/{pipeline}` | | `funnel_product_list` | List products | read | `funnel:read` | `GET /api/v1/funnel/products` | | `funnel_product_save` | Add or change a product | write | `funnel:write` | `POST /api/v1/funnel/products` (+1) | | `funnel_report_get` | Read a funnel report | read | `funnel:read` | `GET /api/v1/funnel/reports` | | `funnel_stage_archive` | Archive a stage | write (destructive) | `funnel:write` | `DELETE /api/v1/funnel/stages/{stage}` | | `funnel_stage_create` | Add a stage | write | `funnel:write` | `POST /api/v1/funnel/pipelines/{pipeline}/stages` | | `funnel_stage_update` | Change or reorder stages | write | `funnel:write` | `PUT /api/v1/funnel/pipelines/{pipeline}/stages` (+1) | ## Related {#related} - [Venom Funnel](/docs/cloud/funnel.md): the board, deals, products, goals and reports. - [Funnel guides](/docs/funnel.md) and [Outreach](/docs/funnel/outreach.md): sequences, channels, safety rules and how drafts are written. - [Venom People](/docs/cloud/people.md): the people and companies deals link. - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Venom Calendar URL: https://cloud.usevenom.dev/docs/developers/calendar Description: Work with a member's calendar from code or an agent. Find free times, book and move meetings, manage event types and schedules, send time offers and group polls over REST or MCP, and put booking pages on your own site. Venom Calendar is each member's own booking calendar: a profile (the `/meet/` page), working-hour schedules, event types and their bookings, plus the calendars and `.ics` feeds that block busy time. Every console action is an MCP tool, and each tool has a REST route under `/api/v1/calendar`. Booking pages also have a public API that needs no credential. ## What you can build {#build} - **Booking from your product.** Find free times for an event type (`GET /api/v1/calendar/slots`) and book one for a customer (`POST /api/v1/calendar/bookings`), confirmed at once. - **Meeting changes from your CRM.** Move or cancel a booking (`POST /api/v1/calendar/bookings/{booking_id}/reschedule`, `…/cancel`) and accept or decline requests on event types with manual confirmation (`…/confirm`). - **Links for one person.** Make a single-use or one-off booking link (`POST /api/v1/calendar/links`) and send it from your own system. - **An agent that schedules for you.** Connect `venom-calendar`: the agent offers a few held times (`calendar_offer_create`), sends them (`calendar_offer_send`) and books the one the person picks (`calendar_offer_accept`). - **Group scheduling.** Create a poll for several people (`POST /api/v1/calendar/polls`) and close it on the winning time (`…/polls/{poll_id}/close`). - **A booking page on your site.** Embed `/meet//` with one script and listen for the booking ([Embedding](/docs/calendar/embed.md)). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/calendar`, server name `venom-calendar` | | Connect | `claude mcp add --transport http venom-calendar https://cloud.usevenom.dev/workspace/mcp/calendar` | | MCP tools | 41 (16 read, 25 write) | | OAuth scopes | `calendar:read` `calendar:write` | | REST twin | 43 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `calendar.booking.created`, `calendar.booking.confirmed`, `calendar.booking.rescheduled`, `calendar.booking.cancelled`, `calendar.booking.no_show` | ## Authentication and scopes {#scopes} A calendar belongs to one member, so every caller must be a member: - A **personal API key** acts as its member. Turn on "This key is mine" when you create it. - A **team key** has no member and gets no calendar. Every calendar tool answers that it needs a member's personal key or OAuth. - An **OAuth app** acts as the member who connected it. It needs `calendar:read` to use the tools at all and `calendar:write` to change anything. The member's org role then decides: - Every member, whatever their role, reads and changes their own profile, schedules, bookings, offers, polls, feeds and connected accounts. - Event types and their team hosts (`calendar_event_type_save`, `calendar_event_type_delete`, `calendar_event_type_hosts_set`) need a role that writes in Calendar: owner, admin or developer. Billing members and viewers are refused. - A read-only key, or an OAuth grant without `calendar:write`, only reads. An agent's booking goes through the same race-safe path as the public page. Sending an offer (`calendar_offer_send`) goes through Comms, so an agent's send waits for a person's approval unless the Comms profile allows agents ([Agents schedule for you](/docs/calendar/agents.md)). ## Worked example {#example} Find free afternoon times for an event type next week, then book one for a customer: ```bash curl "$VENOM_CLOUD/api/v1/calendar/slots?event_type_id=&from=2026-11-16T00:00:00Z&to=2026-11-21T00:00:00Z&time_zone=Europe/London&prefer=afternoon&limit=5" \ -H "Authorization: Bearer $VENOM_API_KEY" curl -X POST "$VENOM_CLOUD/api/v1/calendar/bookings" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Idempotency-Key: demo-dana-2026-11-17' \ -d '{"event_type_id": "", "start": "2026-11-17T14:00:00Z", "invitee": {"name": "Dana Reyes", "email": "dana@example.com", "time_zone": "Europe/London"}}' ``` The booking answers `201`. A time someone else took first answers `slot_taken` with the next free times; a retry with the same `Idempotency-Key` returns the first result. The same over MCP, from a client connected to `/workspace/mcp/calendar`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "calendar_slots_find", "arguments": { "event_type_id": "", "from": "2026-11-16T00:00:00Z", "to": "2026-11-21T00:00:00Z", "time_zone": "Europe/London", "prefer": "afternoon", "limit": 5 } } } ``` ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "calendar_booking_create", "arguments": { "event_type_id": "", "start": "2026-11-17T14:00:00Z", "invitee": { "name": "Dana Reyes", "email": "dana@example.com", "time_zone": "Europe/London" }, "idempotency_key": "demo-dana-2026-11-17" } } } ``` Over MCP, `idempotency_key` is required (8 to 200 characters). List event types and their ids with `calendar_event_type_list` (`GET /api/v1/calendar/event-types`). ## The public booking API {#public} The booking pages use an API that is open to anyone, under `/meet/api`: `GET /meet/api/`, and for an event type (`/meet/api//`) or a link (`/meet/api/l/`) `POST …/open`, `GET …/slots`, `POST …/holds` and `POST …/book`. It is rate limited per visitor and needs the page token and a small proof of work, so build on it through the embed script rather than calling it from a server. Details and limits: [Booking pages](/docs/calendar/booking-pages.md#agents). ## Events {#events} 5 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `calendar.booking.created` | Someone booked a time on a Venom Calendar booking page (or the owner booked for them): the booking, event type, time, status (confirmed, or pending when it needs your confirmation), and the invitee's name, email and time zone. Never their answers. | | `calendar.booking.confirmed` | The owner confirmed a pending booking. | | `calendar.booking.rescheduled` | A booking moved to a new time, by the invitee from their link or by the owner: the new time, the previous one and the invite's sequence. | | `calendar.booking.cancelled` | A booking was cancelled by the invitee or the owner, or a pending one was declined: the reason given, if any. | | `calendar.booking.no_show` | The owner marked a booking as a no-show after its start: the booking, its time and the invitee (Funnel can move the deal back). | An embedded booking page also fires a `venom-meet:booked` DOM event on your page when someone books, with the booking id and start ([Embedding](/docs/calendar/embed.md#when-someone-books)). The webhook payload fields are listed on [Booking pages](/docs/calendar/booking-pages.md#events). ## REST routes {#rest} The REST twin: 43 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/calendar/profile** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/profile` | Your booking profile (the /meet/ page) | `calendar_profile_get` | | PUT | `/api/v1/calendar/profile` | Create or change your booking profile | `calendar_profile_save` | **/calendar/schedules** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/schedules` | Your working-hour schedules | `calendar_schedule_list` | | POST | `/api/v1/calendar/schedules` | Add a working-hour schedule | `calendar_schedule_save` | | PUT | `/api/v1/calendar/schedules/{schedule_id}` | Change a schedule | `calendar_schedule_save` | | DELETE | `/api/v1/calendar/schedules/{schedule_id}` | Delete a schedule (its event types fall back to the default) | `calendar_schedule_delete` | **/calendar/event-types** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/event-types` | Your bookable kinds of meeting | `calendar_event_type_list` | | POST | `/api/v1/calendar/event-types` | Add an event type | `calendar_event_type_save` | | GET | `/api/v1/calendar/event-types/{event_type_id}` | Read an event type with all its rules | `calendar_event_type_get` | | PUT | `/api/v1/calendar/event-types/{event_type_id}` | Change an event type (fields left out keep their value) | `calendar_event_type_save` | | DELETE | `/api/v1/calendar/event-types/{event_type_id}` | Delete an event type (its bookings stay) | `calendar_event_type_delete` | | GET | `/api/v1/calendar/event-types/{event_type_id}/hosts` | An event type's kind, round-robin rules and hosts | `calendar_event_type_hosts_get` | | PUT | `/api/v1/calendar/event-types/{event_type_id}/hosts` | Make an event type collective or round robin, and set its hosts | `calendar_event_type_hosts_set` | **/calendar/links** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/calendar/links` | A single-use or one-off booking link (shown once) | `calendar_link_create` | **/calendar/slots** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/slots` | Free times for an event type | `calendar_slots_find` | **/calendar/bookings** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/bookings` | Bookings, newest first | `calendar_booking_list` | | POST | `/api/v1/calendar/bookings` | Book a free time for someone (confirmed at once; a taken time answers slot_taken with the next free times) | `calendar_booking_create` | | GET | `/api/v1/calendar/bookings/{booking_id}` | Read a booking | `calendar_booking_get` | | POST | `/api/v1/calendar/bookings/{booking_id}/reschedule` | Move a booking to a new start (same invite, sequence + 1) | `calendar_booking_reschedule` | | POST | `/api/v1/calendar/bookings/{booking_id}/cancel` | Cancel a booking and remove its calendar event | `calendar_booking_cancel` | | POST | `/api/v1/calendar/bookings/{booking_id}/confirm` | Accept or decline (accept: false) a pending booking | `calendar_booking_confirm` | | POST | `/api/v1/calendar/bookings/{booking_id}/no-show` | Mark a past booking as a no-show (rebook: true emails a fresh link) | `calendar_booking_mark_no_show` | | POST | `/api/v1/calendar/bookings/{booking_id}/resend-invite` | Email the invitee the calendar invite again | `calendar_booking_resend_invite` | **/calendar/reminders** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/reminders` | Invites, reminders and follow-ups, with why one fell back or wasn't sent | `calendar_reminder_list` | **/calendar/offers** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/offers` | Your offers, newest first, with any reply waiting | `calendar_offer_list` | | POST | `/api/v1/calendar/offers` | Find and hold a few free times for one person, with a single-use link and a ready text | `calendar_offer_create` | | GET | `/api/v1/calendar/offers/{offer_id}` | Read an offer: the times still held, the link, sends and the reply | `calendar_offer_get` | | POST | `/api/v1/calendar/offers/{offer_id}/cancel` | Withdraw an offer: release the held times and stop the link | `calendar_offer_cancel` | | POST | `/api/v1/calendar/offers/{offer_id}/send` | Send the offer through Comms or email (an agent's send waits for approval unless a profile allows agents) | `calendar_offer_send` | | POST | `/api/v1/calendar/offers/{offer_id}/accept` | Book the offered time the invitee chose; the other holds go | `calendar_offer_accept` | | POST | `/api/v1/calendar/offers/{offer_id}/dismiss` | Clear an offer's reply suggestion | `calendar_offer_dismiss` | **/calendar/polls** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/polls` | Your group polls | `calendar_poll_list` | | POST | `/api/v1/calendar/polls` | Propose times to a group and get a link to send (the times are held) | `calendar_poll_create` | | GET | `/api/v1/calendar/polls/{poll_id}` | A group poll with everyone's answers | `calendar_poll_get` | | POST | `/api/v1/calendar/polls/{poll_id}/close` | Book the chosen time for everyone who can make it, or just close the poll | `calendar_poll_close` | **/calendar/accounts** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/accounts` | Your connected calendar accounts (Google, Microsoft, CalDAV) | `calendar_account_list` | | DELETE | `/api/v1/calendar/accounts/{account_id}` | Disconnect a calendar account (its calendars stop being checked) | `calendar_account_remove` | **/calendar/calendars** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/calendars` | The calendars of your connected accounts, with what each is used for | `calendar_calendar_list` | | PATCH | `/api/v1/calendar/calendars/{calendar_id}` | Change how a calendar is used: conflicts, busy rules, invites, colour, time zone | `calendar_calendar_update` | **/calendar/feeds** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/calendar/feeds` | The ICS feeds you subscribed to as busy time | `calendar_feed_list` | | POST | `/api/v1/calendar/feeds` | Subscribe to an ICS feed as busy time | `calendar_feed_add` | | PATCH | `/api/v1/calendar/feeds/{feed}` | Rename a feed or change its URL | `calendar_feed_update` | | DELETE | `/api/v1/calendar/feeds/{feed}` | Stop subscribing to a feed | `calendar_feed_remove` | Every calendar tool has a REST route, connected accounts (`GET /api/v1/calendar/accounts`), their calendars (`GET /api/v1/calendar/calendars`, `PATCH …/calendars/{calendar_id}`), `.ics` feeds (`/api/v1/calendar/feeds`) and reminders (`GET /api/v1/calendar/reminders`) included. ## MCP tools {#tools} 41 tools: 16 read, 25 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `calendar_account_list` | List calendar accounts | read | `calendar:read` | `GET /api/v1/calendar/accounts` | | `calendar_account_remove` | Disconnect a calendar account | write (destructive) | `calendar:write` | `DELETE /api/v1/calendar/accounts/{account_id}` | | `calendar_booking_cancel` | Cancel a booking | write (destructive) | `calendar:write` | `POST /api/v1/calendar/bookings/{booking_id}/cancel` | | `calendar_booking_confirm` | Confirm or decline a request | write | `calendar:write` | `POST /api/v1/calendar/bookings/{booking_id}/confirm` | | `calendar_booking_create` | Book a time | write | `calendar:write` | `POST /api/v1/calendar/bookings` | | `calendar_booking_get` | Read a booking | read | `calendar:read` | `GET /api/v1/calendar/bookings/{booking_id}` | | `calendar_booking_list` | List bookings | read | `calendar:read` | `GET /api/v1/calendar/bookings` | | `calendar_booking_mark_no_show` | Mark a no-show | write | `calendar:write` | `POST /api/v1/calendar/bookings/{booking_id}/no-show` | | `calendar_booking_reschedule` | Move a booking | write | `calendar:write` | `POST /api/v1/calendar/bookings/{booking_id}/reschedule` | | `calendar_booking_resend_invite` | Resend the invite | write | `calendar:write` | `POST /api/v1/calendar/bookings/{booking_id}/resend-invite` | | `calendar_calendar_list` | List calendars | read | `calendar:read` | `GET /api/v1/calendar/calendars` | | `calendar_calendar_update` | Change a calendar's rules | write | `calendar:write` | `PATCH /api/v1/calendar/calendars/{calendar_id}` | | `calendar_event_type_delete` | Delete an event type | write (destructive) | `calendar:write` | `DELETE /api/v1/calendar/event-types/{event_type_id}` | | `calendar_event_type_get` | Read an event type | read | `calendar:read` | `GET /api/v1/calendar/event-types/{event_type_id}` | | `calendar_event_type_hosts_get` | Read an event type's hosts | read | `calendar:read` | `GET /api/v1/calendar/event-types/{event_type_id}/hosts` | | `calendar_event_type_hosts_set` | Set an event type's hosts | write | `calendar:write` | `PUT /api/v1/calendar/event-types/{event_type_id}/hosts` | | `calendar_event_type_list` | List event types | read | `calendar:read` | `GET /api/v1/calendar/event-types` | | `calendar_event_type_save` | Save an event type | write | `calendar:write` | `POST /api/v1/calendar/event-types` (+1) | | `calendar_feed_add` | Add an .ics feed | write | `calendar:write` | `POST /api/v1/calendar/feeds` | | `calendar_feed_list` | List .ics feeds | read | `calendar:read` | `GET /api/v1/calendar/feeds` | | `calendar_feed_remove` | Remove an .ics feed | write (destructive) | `calendar:write` | `DELETE /api/v1/calendar/feeds/{feed}` | | `calendar_feed_update` | Change an .ics feed | write | `calendar:write` | `PATCH /api/v1/calendar/feeds/{feed}` | | `calendar_link_create` | Create a booking link | write | `calendar:write` | `POST /api/v1/calendar/links` | | `calendar_offer_accept` | Book an offered time | write | `calendar:write` | `POST /api/v1/calendar/offers/{offer_id}/accept` | | `calendar_offer_cancel` | Withdraw an offer | write (destructive) | `calendar:write` | `POST /api/v1/calendar/offers/{offer_id}/cancel` | | `calendar_offer_create` | Offer times to someone | write | `calendar:write` | `POST /api/v1/calendar/offers` | | `calendar_offer_dismiss` | Dismiss a reply | write | `calendar:write` | `POST /api/v1/calendar/offers/{offer_id}/dismiss` | | `calendar_offer_get` | Read an offer | read | `calendar:read` | `GET /api/v1/calendar/offers/{offer_id}` | | `calendar_offer_list` | List offers | read | `calendar:read` | `GET /api/v1/calendar/offers` | | `calendar_offer_send` | Send an offer | write | `calendar:write` | `POST /api/v1/calendar/offers/{offer_id}/send` | | `calendar_poll_close` | Close a group poll | write | `calendar:write` | `POST /api/v1/calendar/polls/{poll_id}/close` | | `calendar_poll_create` | Create a group poll | write | `calendar:write` | `POST /api/v1/calendar/polls` | | `calendar_poll_get` | Read a group poll | read | `calendar:read` | `GET /api/v1/calendar/polls/{poll_id}` | | `calendar_poll_list` | List group polls | read | `calendar:read` | `GET /api/v1/calendar/polls` | | `calendar_profile_get` | Read the booking profile | read | `calendar:read` | `GET /api/v1/calendar/profile` | | `calendar_profile_save` | Save the booking profile | write | `calendar:write` | `PUT /api/v1/calendar/profile` | | `calendar_reminder_list` | List invites and reminders | read | `calendar:read` | `GET /api/v1/calendar/reminders` | | `calendar_schedule_delete` | Delete a schedule | write (destructive) | `calendar:write` | `DELETE /api/v1/calendar/schedules/{schedule_id}` | | `calendar_schedule_list` | List schedules | read | `calendar:read` | `GET /api/v1/calendar/schedules` | | `calendar_schedule_save` | Save a schedule | write | `calendar:write` | `POST /api/v1/calendar/schedules` (+1) | | `calendar_slots_find` | Find free times | read | `calendar:read` | `GET /api/v1/calendar/slots` | ## Related {#related} - [Booking pages](/docs/calendar/booking-pages.md), [Agents schedule for you](/docs/calendar/agents.md), [Embedding](/docs/calendar/embed.md), [.ics feeds](/docs/calendar/ics-feeds.md) and [Team scheduling](/docs/calendar/teams.md). - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks](/docs/developers/webhooks.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Venom Comms URL: https://cloud.usevenom.dev/docs/developers/comms Description: Send messages and place phone calls from your app or an agent. Text people on SMS, WhatsApp, RCS, Telegram or email, run fallback profiles, read conversations and follow replies over the Comms API or MCP. Venom Comms sends messages and places calls through the providers your org configured (Settings, Comms). Apps use the Comms API under `/v1/comms` with an org API key. Agents use the `comms_*` MCP tools, where a person approves each send unless a profile allows agents. The tools also have a REST twin under `/api/v1/comms` (one route per tool, the same arguments), for scripts that act as an agent rather than as an application. ## What you can build {#build} - **Notifications from your app.** Send an SMS, WhatsApp, RCS, Telegram or email message (`POST /v1/comms/messages`) with an `Idempotency-Key`, so a retry never sends twice. - **Phone confirmations.** Place a call that reads a script and listens for a key press (`POST /v1/comms/calls`), then read the digits from the call's `gathered` or a `comms.call.gather` webhook. - **Escalation with fallback.** Start a profile such as `page` (SMS, then a call if nobody acknowledges) with `profile` instead of `channel`, follow it with `GET /v1/comms/dispatches/{id}` and stop it with `POST /v1/comms/dispatches/{id}/ack`. - **A reply handler.** Read inbound messages from the event feed (`GET /v1/comms/events?after=`) or subscribe a webhook to `comms.message.received`. - **An agent that drafts outreach.** Connect `venom-comms` and let an agent read a conversation (`comms_conversation_get`) and ask to send a reply (`comms_message_send`); a person approves it before it goes out. - **Opt-out sync.** Push your own unsubscribe list into Comms (`POST /v1/comms/optouts`), so no product contacts those people. - **Approvals from your phone or chat.** Show an owner the sends waiting (`GET /v1/comms/messages?status=pending_approval`) and let them approve or reject each one (`POST /v1/comms/messages/{id}/approve`, `…/reject`, or `comms_message_approve` over MCP). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/comms`, server name `venom-comms` | | Connect | `claude mcp add --transport http venom-comms https://cloud.usevenom.dev/workspace/mcp/comms` | | MCP tools | 27 (13 read, 14 write) | | OAuth scopes | `comms:read` `comms:write` | | REST twin | 27 routes under `https://cloud.usevenom.dev/api/v1` | | Comms API | 28 operations | | Webhook events | `comms.message.received`, `comms.message.status`, `comms.call.answered`, `comms.call.gather`, `comms.call.ended`, `comms.call.status`, `comms.dispatch.acknowledged` | ## Authentication and scopes {#scopes} Comms treats an app and an agent differently: - **An API key on `/v1/comms`** (`vck_…`, personal or team) is an application your org made. Its sends go out at once, subject to opt-outs, quiet hours and the org's per-minute limit. It cannot change Comms settings, and it can lift only the opt-outs that the API added. - **An API key on MCP** is an agent. It may read and ask to send. A service agent that an admin made read-only, or scoped to other apps, is refused in words. - **An OAuth app** is an agent too. It needs `comms:read` to use the tools at all and `comms:write` to send or add an opt-out. `/v1/comms` takes its token as well, when the token was issued for the workspace (`/workspace/mcp`) with comms scopes: it is still an agent there, so its sends wait for approval, and `comms:read` alone only reads. What happens to an agent's send: | The call | Result | |---|---| | `comms_message_send` or `comms_call_place` with a `channel` or a script | stored with status `pending_approval`; it goes out when a person approves it in Settings, Comms, or is canceled if they reject it | | With a `profile` an admin opened to agents ("Agents may send without approval") | goes out at once | | With any other `profile` | refused: `403 approval_required`, with a message that names the profile | ### Approving from another app {#approve} A person can approve or reject a waiting send without opening the console: `POST /v1/comms/messages/{id}/approve` or `…/reject` (and `/v1/comms/calls/{id}/…`), or the tools `comms_message_approve`, `comms_message_reject`, `comms_call_approve` and `comms_call_reject` (`/api/v1/comms/messages/{message}/approve` on the twin). The rule is the console's, plus one: - The credential is a person's: an OAuth app with `comms:write`, or the member's own personal API key. A team or service key is refused, because no person stands behind it. - The member's role manages Comms (owner or admin). Developers, billing members and viewers are refused. - An agent never approves its own send. The credential that asked is refused, and so is every other credential of the same member (their other OAuth apps and personal keys), so an approval always takes a second party. Approving sends the message (or places the call) at once and answers it; rejecting sets it `canceled`. A send that is no longer waiting answers `404`. Each decision is in the audit log (`comms.approved`, `comms.rejected`) with the approver as actor. An opted-out contact gets status `blocked` and is never contacted. A non-urgent send in the recipient's quiet hours is `scheduled` until they end. Profiles and who may use them are on [Profiles](/docs/comms/profiles.md). ## Worked example {#example} Text a customer that their order shipped, safe to retry, then read its status: ```bash curl -X POST "$VENOM_CLOUD/v1/comms/messages" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -H 'Idempotency-Key: order-4411-shipped' \ -d '{"to": "+15551234567", "channel": "sms", "body": "Your order 4411 shipped.", "subject": "order:4411"}' curl "$VENOM_CLOUD/v1/comms/messages/" \ -H "Authorization: Bearer $VENOM_API_KEY" ``` The first call answers `201` with the message; `status` moves from `queued` through `sent` to `delivered`. Over MCP, from a client connected to `/workspace/mcp/comms`, the same send waits for a person: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "comms_message_send", "arguments": { "to": "+15551234567", "channel": "sms", "body": "Your order 4411 shipped.", "idempotency_key": "order-4411-shipped" } } } ``` The answer says "Asked to send" and the message's status is `pending_approval`. Read it later with `comms_message_get` and its `message` id. Without a provider, sends answer `409 comms_not_configured`. To try the flow first, add the fake provider in Settings, Comms and drive replies with `POST /v1/comms/simulate` ([The Comms API](/docs/comms/api.md#trying-it-without-a-provider)). ## Errors worth handling {#errors} | Status, code | What to do | |---|---| | `409 comms_not_configured` | the org has no enabled provider for that channel: add one in Settings, Comms | | `409 no_sender` | the provider has no sender for that channel | | `400 whatsapp_template_required` | WhatsApp outside the 24-hour window: send an approved `template` (`GET /v1/comms/templates`) | | `403 approval_required` | an agent named a profile that is not open to agents | | `429 rate_limit_exceeded` | over the org's per-minute limit for messages and calls together; wait for `retry-after` | ## Events {#events} 7 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `comms.message.received` | Someone wrote to one of the org's numbers (Venom Comms): the channel, the sender, the conversation and the text, plus what it asked for (ack, escalate, STOP). | | `comms.message.status` | A message sent through Venom Comms changed status (sent, delivered, read, failed), with the provider's reason on a failure. | | `comms.call.answered` | A call placed through Venom Comms was answered. | | `comms.call.gather` | The person on a Venom Comms call pressed keys at a gather step: the step's name and the digits. | | `comms.call.ended` | A Venom Comms call ended: its result, duration and cost. | | `comms.call.status` | A Venom Comms call changed status (ringing, failed, busy, no answer). | | `comms.dispatch.acknowledged` | Someone acknowledged a Venom Comms profile run (a reply of 1 or ack, or key 1 on the call): no further steps go out. | The same events are a feed: `GET /v1/comms/events?after=` returns them oldest first, in the envelope the webhooks carry, except that the feed has an inbound message's body and the webhook has only its length. Pass `next_cursor` back as `after`. See [The Comms API](/docs/comms/api.md#events). ## REST routes {#rest} The REST twin: 27 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/comms/messages** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/messages` | Recent messages, newest first | `comms_message_list` | | POST | `/api/v1/comms/messages` | Send a message on a channel, or run a profile (an agent's send waits for a person's approval unless the profile allows agents) | `comms_message_send` | | GET | `/api/v1/comms/messages/{message}` | One message and its delivery status | `comms_message_get` | | POST | `/api/v1/comms/messages/{message}/approve` | A person sends an agent's pending message (owner or admin; never the credential that asked) | `comms_message_approve` | | POST | `/api/v1/comms/messages/{message}/reject` | A person cancels an agent's pending message (owner or admin; never the credential that asked) | `comms_message_reject` | **/comms/calls** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/calls` | Recent calls, newest first | `comms_call_list` | | POST | `/api/v1/comms/calls` | Call a person with a short script, or run a profile (an agent's call waits for approval unless the profile allows agents) | `comms_call_place` | | GET | `/api/v1/comms/calls/{call}` | One call: status, duration, cost and the digits pressed | `comms_call_get` | | POST | `/api/v1/comms/calls/{call}/approve` | A person places an agent's pending call (owner or admin; never the credential that asked) | `comms_call_approve` | | POST | `/api/v1/comms/calls/{call}/reject` | A person cancels an agent's pending call (owner or admin; never the credential that asked) | `comms_call_reject` | **/comms/conversations** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/conversations` | Threads with contacts, newest first | `comms_conversation_list` | | GET | `/api/v1/comms/conversations/{conversation}` | One thread with its messages and calls | `comms_conversation_get` | | POST | `/api/v1/comms/conversations/{conversation}/read` | Mark the contact's messages read (WhatsApp's blue ticks) | `comms_receipt_send` | **/comms/senders** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/senders` | The org's numbers and sender ids | `comms_sender_list` | | POST | `/api/v1/comms/senders` | Add a number or sender id (a person whose role manages Comms) | `comms_sender_add` | | DELETE | `/api/v1/comms/senders/{sender}` | Remove a sender (a person whose role manages Comms) | `comms_sender_delete` | **/comms/templates** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/templates` | Message templates and their approval state | `comms_template_list` | **/comms/profiles** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/profiles` | Routing profiles and whether agents may use them | `comms_profile_list` | **/comms/optouts** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/optouts` | Contacts who must not be messaged or called | `comms_optout_list` | | POST | `/api/v1/comms/optouts` | Stop all messages and calls to a contact (or one channel) | `comms_optout_add` | **/comms/dispatches** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/dispatches/{dispatch}` | One profile run: its steps and who acknowledged it | `comms_dispatch_get` | **/comms/settings** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/settings` | Quiet hours, time zone, send limit and call voice | `comms_setting_get` | | PATCH | `/api/v1/comms/settings` | Change quiet hours, time zone, send limit or call voice (a person whose role manages Comms) | `comms_setting_update` | **/comms/providers** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/comms/providers` | Providers and mailboxes, without secrets or webhook URLs (a person whose role manages Comms) | `comms_provider_list` | | PATCH | `/api/v1/comms/providers/{provider}` | Enable, disable, rename or reorder a provider (a person whose role manages Comms) | `comms_provider_update` | | DELETE | `/api/v1/comms/providers/{provider}` | Remove a provider or mailbox (a person whose role manages Comms) | `comms_provider_delete` | | POST | `/api/v1/comms/providers/{provider}/test` | Sign in to a mailbox and check its domain's DNS (a person whose role manages Comms) | `comms_mailbox_test` | Also the Comms API: 28 operations, generated from `services/nodejs-cloud/contracts/comms-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. **/v1/comms** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/v1/comms/messages` | Recent messages, newest first | key or token | | POST | `/v1/comms/messages` | Send a message on a channel, or start a routing profile | key or token | | GET | `/v1/comms/messages/{id}` | | key or token | | POST | `/v1/comms/messages/{id}/approve` | Send an agent's pending message | key or token | | POST | `/v1/comms/messages/{id}/reject` | Cancel an agent's pending message | key or token | | GET | `/v1/comms/calls` | | key or token | | POST | `/v1/comms/calls` | Place a call that plays a script, or start a routing profile | key or token | | GET | `/v1/comms/calls/{id}` | | key or token | | POST | `/v1/comms/calls/{id}/approve` | Place an agent's pending call | key or token | | POST | `/v1/comms/calls/{id}/reject` | Cancel an agent's pending call | key or token | | GET | `/v1/comms/conversations` | Threads (one per channel and contact), newest first | key or token | | GET | `/v1/comms/conversations/{id}` | | key or token | | GET | `/v1/comms/senders` | The org's numbers and sender ids | key or token | | GET | `/v1/comms/templates` | Message templates and their approval state (WhatsApp outside the 24-hour window sends an approved one) | key or token | | POST | `/v1/comms/templates/sync` | Read the providers' templates and their approval state again | key or token | | GET | `/v1/comms/profiles` | Routing profiles, the org's and the built-in page, support and notify | key or token | | GET | `/v1/comms/optouts` | | key or token | | POST | `/v1/comms/optouts` | Record that a contact must not be contacted on a channel (or any, "*") | key or token | | DELETE | `/v1/comms/optouts` | Lift an opt-out an API key added (a person lifts any in the console) | key or token | | GET | `/v1/comms/dispatches/{id}` | A profile run and where it is | key or token | | POST | `/v1/comms/dispatches/{id}/ack` | Acknowledge a profile run so no further steps go out | key or token | | GET | `/v1/comms/events` | The event feed after a cursor, oldest first | key or token | | POST | `/v1/comms/simulate` | Apply a fake provider's callback (fake providers only) | key or token | **/api** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/api/integrations/comms/line/session` | Venom Line, the media bridge exchanges a call's ticket for a session (not for API clients) | none | | POST | `/api/integrations/comms/line/tools` | Venom Line, one of the line's tools for a live call's agent (not for API clients) | none | | POST | `/api/integrations/comms/line/report` | Venom Line, a call's transcript and measured latencies once it ends (not for API clients) | none | | POST | `/api/integrations/comms/{provider}/{token}/{route}` | A provider's callback (not for API clients) | none | | GET | `/api/integrations/comms/{provider}/{token}/tts/{call}/{step}` | A call step spoken in the org's own TTS voice (fetched by the provider) | none | The `/api/integrations/comms/…` routes are provider callbacks and Venom Line's own; your app does not call them. Field-by-field reference, call script steps and statuses: [The Comms API](/docs/comms/api.md). ## MCP tools {#tools} 27 tools: 13 read, 14 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `comms_call_approve` | Approve a pending call | write | `comms:write` | `POST /api/v1/comms/calls/{call}/approve` | | `comms_call_get` | Read a call | read | `comms:read` | `GET /api/v1/comms/calls/{call}` | | `comms_call_list` | List calls | read | `comms:read` | `GET /api/v1/comms/calls` | | `comms_call_place` | Place a phone call | write | `comms:write` | `POST /api/v1/comms/calls` | | `comms_call_reject` | Reject a pending call | write (destructive) | `comms:write` | `POST /api/v1/comms/calls/{call}/reject` | | `comms_conversation_get` | Read a conversation | read | `comms:read` | `GET /api/v1/comms/conversations/{conversation}` | | `comms_conversation_list` | List conversations | read | `comms:read` | `GET /api/v1/comms/conversations` | | `comms_dispatch_get` | Read a dispatch | read | `comms:read` | `GET /api/v1/comms/dispatches/{dispatch}` | | `comms_mailbox_test` | Test a mailbox | write | `comms:write` | `POST /api/v1/comms/providers/{provider}/test` | | `comms_message_approve` | Approve a pending message | write | `comms:write` | `POST /api/v1/comms/messages/{message}/approve` | | `comms_message_get` | Read a message | read | `comms:read` | `GET /api/v1/comms/messages/{message}` | | `comms_message_list` | List messages | read | `comms:read` | `GET /api/v1/comms/messages` | | `comms_message_reject` | Reject a pending message | write (destructive) | `comms:write` | `POST /api/v1/comms/messages/{message}/reject` | | `comms_message_send` | Send a message | write | `comms:write` | `POST /api/v1/comms/messages` | | `comms_optout_add` | Opt a contact out | write | `comms:write` | `POST /api/v1/comms/optouts` | | `comms_optout_list` | List opt-outs | read | `comms:read` | `GET /api/v1/comms/optouts` | | `comms_profile_list` | List profiles | read | `comms:read` | `GET /api/v1/comms/profiles` | | `comms_provider_delete` | Remove a provider | write (destructive) | `comms:write` | `DELETE /api/v1/comms/providers/{provider}` | | `comms_provider_list` | List providers | read | `comms:read` | `GET /api/v1/comms/providers` | | `comms_provider_update` | Enable, disable or rename a provider | write | `comms:write` | `PATCH /api/v1/comms/providers/{provider}` | | `comms_receipt_send` | Mark a conversation read | write | `comms:write` | `POST /api/v1/comms/conversations/{conversation}/read` | | `comms_sender_add` | Add a sender | write | `comms:write` | `POST /api/v1/comms/senders` | | `comms_sender_delete` | Remove a sender | write (destructive) | `comms:write` | `DELETE /api/v1/comms/senders/{sender}` | | `comms_sender_list` | List senders | read | `comms:read` | `GET /api/v1/comms/senders` | | `comms_setting_get` | Read Comms settings | read | `comms:read` | `GET /api/v1/comms/settings` | | `comms_setting_update` | Change Comms settings | write | `comms:write` | `PATCH /api/v1/comms/settings` | | `comms_template_list` | List message templates | read | `comms:read` | `GET /api/v1/comms/templates` | ## Related {#related} - [Venom Comms](/docs/comms.md), [The Comms API](/docs/comms/api.md), [Profiles](/docs/comms/profiles.md), [Providers](/docs/comms/providers.md) and [Compliance](/docs/comms/compliance.md). - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks](/docs/developers/webhooks.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Venom Support URL: https://cloud.usevenom.dev/docs/developers/support Description: Read and triage the support inbox from code or an agent. Assign and tag conversations, add internal notes, draft replies from your notes and send them once a person approves, over REST or MCP. Venom Support is the organisation's shared inbox: email, Forms responses, the chat widget and messaging channels in one list of conversations. The inbox, the conversation page, saved replies, SLA policies and the report are MCP tools on `/workspace/mcp/support` and REST routes under `/api/v1/support`. ## What you can build {#build} - **Triage on arrival.** Subscribe to `support.conversation.created`, read the conversation (`GET /api/v1/support/conversations/{conversation}`), then set priority and tags (`PATCH`) and assign it to a member or team (`POST …/assign`). - **Draft-then-approve replies.** Have an agent write a reply from your notes with citations (`support_draft_create`), and send it with `support_reply_send` (`use_draft: true`) only after a person approved the text. - **Watch automatic replies.** When the org turned on [automatic replies](/docs/cloud/support#automatic-replies), list the drafts waiting to send and today's count (`support_autoreply_get`, `GET /api/v1/support/auto-reply`), and hold one or change its text before it goes (`support_draft_update`, `PATCH /api/v1/support/conversations/{conversation}/draft`). Turning automatic replies on is a person's decision in the console; there is no tool for it. - **Bug escalation.** Turn a conversation into a Venom Tasks issue with the thread summary and a link back (`POST /api/v1/support/conversations/{conversation}/issue`). Or add it to an existing issue as a customer request (`POST /api/v1/support/conversations/{conversation}/requests`, see [customer requests](/docs/cloud/tasks-customer-requests)). - **Breach alerts in your own tools.** Subscribe to `support.sla.breached` and page someone, or read response and resolution times with `GET /api/v1/support/report`. - **Saved replies kept in a repo.** Sync your macros with `support_macro_create`, `support_macro_update` and `support_macro_delete`. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/support`, server name `venom-support` | | Connect | `claude mcp add --transport http venom-support https://cloud.usevenom.dev/workspace/mcp/support` | | MCP tools | 26 (9 read, 17 write) | | OAuth scopes | `support:read` `support:write` | | REST twin | 27 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `support.conversation.created`, `support.sla.breached` | ## Authentication and scopes {#scopes} The inbox belongs to the organisation, not to one member, so a team key works as well as a member's key: - A **personal API key** acts with its member's role: owner, admin and developer read and write; billing and viewer read. A key marked read-only reads only. - A **team key** reads and writes (unless it is read-only). Its notes and replies carry the key's name. - An **OAuth app** needs `support:read` to use the tools and `support:write` to change anything, on top of the member's role. - A **service agent** that an admin scoped to some apps reaches Support only when Support is one of them. The settings tools, `support_sla_policy_save`, `support_sla_policy_delete` and `support_widget_save` (and their REST routes), need an owner's or admin's personal key, or an OAuth app with `support:write` connected by an owner or admin. A team key, a read-only key and every other role are refused with "Only an owner or admin may change …". The inbound secret, the outbound provider and its key are set only in the browser. A conversation assigned to a private org team is visible only to that team's members and the org's owners and admins. A team key is in no team, so it does not see those conversations. There is no add-on gate on Support's tools. `support_draft_create` counts against the org's daily AI cap. A refused change answers `403` over REST, or a tool error that names `support:write` over MCP. The agent's name is on every note and reply it writes. ## Worked example {#example} Pick up the oldest unassigned urgent conversation, assign it, and have a draft ready for a person to check: ```bash curl "$VENOM_CLOUD/api/v1/support/conversations?view=unassigned&priority=urgent&limit=5" \ -H "Authorization: Bearer $VENOM_API_KEY" curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/assign" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"assignee": "ana@example.com"}' curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/draft" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -d '{}' ``` Once Ana approves the draft, send it and close the conversation: ```bash curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/reply" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"use_draft": true, "close": true}' ``` The draft over MCP, from any client connected to `/workspace/mcp/support`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "support_draft_create", "arguments": { "conversation": "42", "format": "json" } } } ``` `{conversation}` is the conversation's id or its number (`42`, or `#42` in a tool argument). `macro` on the draft starts it from a saved reply. ## Sending replies {#replies} `support_reply_send` sends by email through the org's connected provider, with the thread's subject and headers, or, on a messaging conversation (WhatsApp, SMS, RCS, Telegram), through Venom Comms on the channel the customer wrote on. Give `body`, or `use_draft: true` for the pending draft; `close: true` closes the conversation after. - When a reply cannot go out (no provider connected, no customer address, the provider refused), it is saved on the thread as **not sent** and the answer says so: `sent: false` in JSON, with the delivery error. - WhatsApp takes free text only within 24 hours of the customer's last message. After that, the MCP tool takes `template`, `template_language` and `template_params` for an approved template; otherwise the reply goes by SMS when the org's support profile allows it, or is refused. The template arguments are not on the REST route. - The tool descriptions tell an agent to draft first and send only after a person approved the text. The server does not enforce that: your integration should. ## Inbox views and filters {#views} `support_conversation_list` (`GET /api/v1/support/conversations`) takes `view`: `all` (open, the default), `mine`, `teams`, `unassigned`, `snoozed` or `closed`, and filters `query`, `tag`, `priority` (`low`, `normal`, `high`, `urgent`), `assignee` and `team` (an email, id or key, or `none`), `customer`, with `limit` (default 25, at most 100) and `offset`. `support_conversation_get` returns the customer, every message with its delivery state, the pending draft with citations, the linked Tasks issue, the customer's recent Incidents errors and the CSAT rating. `support_conversation_update` changes the subject, priority, tags (`tags`, `add_tags`, `remove_tags`), the customer's name and company, the linked issue, or reopens it. Over MCP it also takes `customer_user_id`, the customer's id in your own product (it matches Incidents error events); that argument is not on the REST route. `support_report_get` covers at most a year and the first 20,000 conversations of the range. ## Events {#events} 2 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `support.conversation.created` | A conversation was opened in Venom Support (email, a form, a messaging channel or by hand): its id, number, subject, channel and priority. Never the customer's message. | | `support.sla.breached` | An open Support conversation ran past its first-reply or resolution time: its id, number, which SLA (first_response or resolution), the due time and the priority. Never the customer's message. | Neither event carries the customer's message: read it with `support_conversation_get`. Mail comes **in** through the org's inbound address, a webhook your mail provider calls with the inbound secret; see [Mail in](/docs/cloud/support-email.md#mail-in). ## REST routes {#rest} The REST twin: 27 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/support/conversations** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/conversations` | The support inbox: conversations by view | `support_conversation_list` | | POST | `/api/v1/support/conversations` | Open a conversation by hand | `support_conversation_create` | | GET | `/api/v1/support/conversations/{conversation}` | Read a conversation with its messages and pending draft | `support_conversation_get` | | PATCH | `/api/v1/support/conversations/{conversation}` | Change a conversation's subject, priority, tags or customer | `support_conversation_update` | | POST | `/api/v1/support/conversations/{conversation}/close` | Close a conversation | `support_conversation_close` | | POST | `/api/v1/support/conversations/{conversation}/snooze` | Snooze a conversation until a time | `support_conversation_snooze` | | POST | `/api/v1/support/conversations/{conversation}/assign` | Assign a conversation to a member and/or a team, or none | `support_conversation_assign` | | GET | `/api/v1/support/conversations/{conversation}/messages` | A conversation's messages | `support_message_list` | | POST | `/api/v1/support/conversations/{conversation}/messages` | Add an internal note | `support_message_create` | | POST | `/api/v1/support/conversations/{conversation}/draft` | Draft a reply with AI from the org's notes (not sent) | `support_draft_create` | | PATCH | `/api/v1/support/conversations/{conversation}/draft` | Change the pending draft's text, or hold an automatic reply | `support_draft_update` | | POST | `/api/v1/support/conversations/{conversation}/reply` | Send a reply through the org's email provider | `support_reply_send` | | POST | `/api/v1/support/conversations/{conversation}/issue` | Create a Tasks issue from a conversation and link it | `support_issue_create` | | POST | `/api/v1/support/conversations/{conversation}/requests` | Add a conversation to a Tasks issue as a customer request | `support_issue_link` | **/support/auto-reply** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/auto-reply` | The automatic-reply settings, today's count and the drafts waiting to send | `support_autoreply_get` | **/support/sla-policies** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/sla-policies` | SLA policies in the order they are tried | `support_sla_policy_list` | | POST | `/api/v1/support/sla-policies` | Create an SLA policy | `support_sla_policy_save` | | PATCH | `/api/v1/support/sla-policies/{policy}` | Change an SLA policy | `support_sla_policy_save` | | DELETE | `/api/v1/support/sla-policies/{policy}` | Delete an SLA policy | `support_sla_policy_delete` | **/support/report** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/report` | First-response and resolution times, breach rate, volume, agent load and ratings for a date range | `support_report_get` | **/support/widget** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/widget` | The chat widget and help center settings and the embed snippet | `support_widget_get` | | PATCH | `/api/v1/support/widget` | Change the chat widget and help center | `support_widget_save` | **/support/help-articles** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/help-articles` | The Notes pages the help center shows | `support_help_article_list` | **/support/macros** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/support/macros` | Saved replies | `support_macro_list` | | POST | `/api/v1/support/macros` | Save a reply | `support_macro_create` | | PATCH | `/api/v1/support/macros/{macro}` | Change a saved reply | `support_macro_update` | | DELETE | `/api/v1/support/macros/{macro}` | Delete a saved reply | `support_macro_delete` | ## MCP tools {#tools} 26 tools: 9 read, 17 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `support_autoreply_get` | Read the automatic-reply settings | read | `support:read` | `GET /api/v1/support/auto-reply` | | `support_conversation_assign` | Assign a support conversation | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/assign` | | `support_conversation_close` | Close a support conversation | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/close` | | `support_conversation_create` | Open a support conversation | write | `support:write` | `POST /api/v1/support/conversations` | | `support_conversation_get` | Read a support conversation | read | `support:read` | `GET /api/v1/support/conversations/{conversation}` | | `support_conversation_list` | List support conversations | read | `support:read` | `GET /api/v1/support/conversations` | | `support_conversation_snooze` | Snooze a support conversation | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/snooze` | | `support_conversation_update` | Change a support conversation | write | `support:write` | `PATCH /api/v1/support/conversations/{conversation}` | | `support_draft_create` | Draft a reply with AI | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/draft` | | `support_draft_update` | Change or hold the pending draft | write | `support:write` | `PATCH /api/v1/support/conversations/{conversation}/draft` | | `support_help_article_list` | List help center articles | read | `support:read` | `GET /api/v1/support/help-articles` | | `support_issue_create` | Create a Tasks issue from a conversation | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/issue` | | `support_issue_link` | Add a conversation to a Tasks issue | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/requests` | | `support_macro_create` | Create a saved reply | write | `support:write` | `POST /api/v1/support/macros` | | `support_macro_delete` | Delete a saved reply | write (destructive) | `support:write` | `DELETE /api/v1/support/macros/{macro}` | | `support_macro_list` | List saved replies | read | `support:read` | `GET /api/v1/support/macros` | | `support_macro_update` | Change a saved reply | write | `support:write` | `PATCH /api/v1/support/macros/{macro}` | | `support_message_create` | Add an internal note | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/messages` | | `support_message_list` | List a conversation's messages | read | `support:read` | `GET /api/v1/support/conversations/{conversation}/messages` | | `support_reply_send` | Send a reply to the customer | write | `support:write` | `POST /api/v1/support/conversations/{conversation}/reply` | | `support_report_get` | Support report | read | `support:read` | `GET /api/v1/support/report` | | `support_sla_policy_delete` | Delete an SLA policy | write (destructive) | `support:write` | `DELETE /api/v1/support/sla-policies/{policy}` | | `support_sla_policy_list` | List SLA policies | read | `support:read` | `GET /api/v1/support/sla-policies` | | `support_sla_policy_save` | Create or change an SLA policy | write | `support:write` | `POST /api/v1/support/sla-policies` (+1) | | `support_widget_get` | Chat widget and help center settings | read | `support:read` | `GET /api/v1/support/widget` | | `support_widget_save` | Change the chat widget and help center | write | `support:write` | `PATCH /api/v1/support/widget` | ## Related {#related} - [Venom Support](/docs/cloud/support.md): the inbox, replies, drafts from your notes and where conversations come from. - [Support email](/docs/cloud/support-email.md), [SLA and reports](/docs/cloud/support-sla.md) and [the chat widget](/docs/cloud/support-widget.md). - [Org webhooks](/docs/developers/webhooks.md), [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Venom Chat URL: https://cloud.usevenom.dev/docs/developers/chat Description: Read channels and DMs, post and reply in threads, react, search, and follow chat with a change cursor from code or an agent, over REST or MCP. A team key joins as an agent member. Venom Chat is the organisation's team chat, where people and agents are both members. Channels, DMs, messages, threads, reactions, search, bookmarks, keyword alerts, product feeds and the channel agent are MCP tools on `/workspace/mcp/chat` and REST routes under `/api/v1/chat`. ## What you can build {#build} - **A bot that answers in threads.** Poll `GET /api/v1/chat/changes` (or `chat_change_list`) for messages that mention it, read the thread with `chat_thread_get`, and reply in it with `POST /api/v1/chat/channels/{channel}/messages` (`thread`, `client_id`). - **Announcements from your CI or deploy tool.** Post a release note to `#releases` with `chat_message_create` and pin it with `chat_message_update` (`pinned`). - **A daily digest.** Read what a member missed with `GET /api/v1/chat/unread`, or search a week of a channel with `GET /api/v1/chat/search` (`since`, `until`). - **Channel setup for a new project.** Create a channel with its members (`POST /api/v1/chat/channels`), have Incidents or Tasks post events to it (`chat_feed_set`), and add the Venom agent, or a service agent of Venom Tasks, with the tools it may use and a level of read-only or post (`chat_agent_set`). - **Triage from chat.** Open a DM or group message with `chat_dm_open` and press a feed message's button (acknowledge a page, approve a flag change) with `chat_feed_press`. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/chat`, server name `venom-chat` | | Connect | `claude mcp add --transport http venom-chat https://cloud.usevenom.dev/workspace/mcp/chat` | | MCP tools | 32 (13 read, 19 write) | | OAuth scopes | `chat:read` `chat:write` | | REST twin | 32 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `chat.channel.created`, `chat.channel.archived`, `chat.message.created` | ## Authentication and scopes {#scopes} Chat always acts as one member, a person or an agent: - A **personal API key** acts as that member. What it posts shows "via MCP" next to the member's name. Owner, admin and developer post; billing and viewer read. An owner's or admin's key is also a Chat admin (archive any channel, delete any message in a channel they can see). A key marked read-only reads only. - A **team key** has no member, so it is an **agent member** named after the key, with the member key `agent:key:`, marked **Agent**. It reads every public channel, joins a public channel by posting in it, and sees a private channel or DM only after a member adds it. It posts unless the key is read-only, and is never a Chat admin. - An **OAuth app** acts as the member who connected it: `chat:read` to read, `chat:write` to post, react, edit, create channels and so on, within the member's role. - A **service agent** that an admin scoped to some apps reaches Chat only when Chat is one of them. Whoever the caller is, it sees only what that member may see. A private channel it is not in answers "No channel called …" or "No such channel", the same as one that does not exist. A credential that may not write is refused in words, with `403` over REST. `chat_channel_read` (mark read) works with read-only credentials. Chat itself has no add-on gate. Two tools do: `chat_feed_set` answers `402 addon_required` when the org does not have the product it would feed, and `chat_file_upload` stores the file in Notes, so it needs the Notes add-on. ## Worked example {#example} Reply in the thread of a message that mentioned your agent, safely retried, then pick up where you left off: ```bash curl -X POST "$VENOM_CLOUD/api/v1/chat/channels/launch/messages" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"text": "Build 482 is green. The release notes are in #releases.", "thread": "", "client_id": "reply-to-"}' curl "$VENOM_CLOUD/api/v1/chat/changes?after=4812" \ -H "Authorization: Bearer $VENOM_API_KEY" ``` The same post over MCP, from any client connected to `/workspace/mcp/chat`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "chat_message_create", "arguments": { "channel": "launch", "text": "Build 482 is green. The release notes are in #releases.", "thread": "", "client_id": "reply-to-" } } } ``` `client_id` makes a retry safe: the same id returns the first message instead of posting again. Derive it from the message you answer. ## Channels, mentions and formats {#formats} - Everywhere a channel is asked for, an id or the channel's name works (`#launch` or `launch`; in a REST path, use the bare name). - Messages are markdown, at most 20,000 characters. Mention a person as `@[Ana](member:ID)` and an agent as `@[Name](agent:ID)`. `chat_member_list` gives each member's whole key (`user:ID` or `agent:ID`). The Venom agent is `@[Venom](agent:venom)`. - Files: upload with `chat_file_upload` (at most 4 MB) and pass the ids in `files` of `chat_message_create`, up to 10. `files` is on the MCP tool only, not on the REST route. - Every tool takes `format: "json"` for structured output. Rate limits are the workspace server's; see [Errors, limits and pagination](/docs/developers/conventions.md). ## Following chat with the change cursor {#changes} ```text chat_change_list {} → Cursor 4812 chat_change_list { after: 4812 } → No changes. Cursor 4812. … someone posts … chat_change_list { after: 4812 } → 4813 new [212] Ana: @[Claude](agent:key:k1) status? … Cursor 4813. ``` Call without `after` to get the current cursor and nothing else, then poll with the cursor each answer returns. When nothing changed, the cursor is the one you sent, so an idle poll costs one short answer. Events are only those in channels you can see: new, edited and deleted messages, reactions, thread counts, joins and renames. `channel` narrows the feed to one channel; `limit` is at most 200. Events are kept for three days. A cursor older than that returns what is kept, so also read `chat_unread_list` after a long gap. A good agent in a channel replies in the thread of the message it was asked about, says what it did, and does not repeat itself on a retry. ## Events {#events} 3 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `chat.channel.created` | A public channel was created in Venom Chat: id, name and who created it. Private channels and direct messages are never sent. | | `chat.channel.archived` | A public channel was archived in Venom Chat (or restored: `archived` false): id, name and who. | | `chat.message.created` | A message was posted in a public channel of Venom Chat, by a person, an agent or a feed: the message id, channel, thread, author and how it was posted. Never the text; private channels and direct messages are never sent. Busy: one event per message. | Chat sends no org webhook events. Follow it with the change cursor above. The live server-sent event stream the Chat app uses takes a signed-in browser session only, not an API key. Events flow the other way through [product feeds](/docs/cloud/chat-feeds.md): Incidents, Tasks, Flags, Experiments and Forms post their events into a channel as messages with buttons. ## REST routes {#rest} The REST twin: 32 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/chat/channels** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/channels` | The channels and DMs you can see, with unread counts | `chat_channel_list` | | POST | `/api/v1/chat/channels` | Create a public, private or team channel | `chat_channel_create` | | GET | `/api/v1/chat/channels/{channel}` | Read a channel with its members | `chat_channel_get` | | PATCH | `/api/v1/chat/channels/{channel}` | Rename, set the topic, add or remove members, mute | `chat_channel_update` | | DELETE | `/api/v1/chat/channels/{channel}` | Archive a channel (restore: true to bring it back) | `chat_channel_archive` | | POST | `/api/v1/chat/channels/{channel}/join` | Join a public channel | `chat_channel_join` | | POST | `/api/v1/chat/channels/{channel}/leave` | Leave a channel | `chat_channel_leave` | | POST | `/api/v1/chat/channels/{channel}/read` | Mark a channel read | `chat_channel_read` | | GET | `/api/v1/chat/channels/{channel}/messages` | A channel's messages, newest page first or after a cursor | `chat_message_list` | | POST | `/api/v1/chat/channels/{channel}/messages` | Post a message or a thread reply | `chat_message_create` | | GET | `/api/v1/chat/channels/{channel}/feeds` | The product feeds on a channel and the ones it could take | `chat_feed_list` | | PUT | `/api/v1/chat/channels/{channel}/feeds` | Set, change or remove (remove: true) a product feed on a channel (owners) | `chat_feed_set` | | GET | `/api/v1/chat/channels/{channel}/agent` | Whether an agent (Venom by default, or a service agent) works in a channel and which tools it may use there | `chat_agent_get` | | PUT | `/api/v1/chat/channels/{channel}/agent` | Add an agent (Venom, or a service agent) to a channel with the tools it may use and its level (read or post), change them, or remove it (remove: true) (owners) | `chat_agent_set` | **/chat/threads** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/threads/{message}` | A thread: the first message and its replies | `chat_thread_get` | **/chat/messages** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/chat/messages/{message}` | Edit your message, or pin or unpin one | `chat_message_update` | | DELETE | `/api/v1/chat/messages/{message}` | Delete a message | `chat_message_delete` | | POST | `/api/v1/chat/messages/{message}/reactions` | Add or remove your reaction | `chat_message_react` | | POST | `/api/v1/chat/messages/{message}/agent-run` | Stop a working agent reply or run a finished one again | `chat_agent_run` | | GET | `/api/v1/chat/messages/{message}/pull-request` | A pull request card's state and its changed files with patches, read from GitHub with the org's own token | `chat_pullrequest_get` | | POST | `/api/v1/chat/messages/{message}/actions` | Press an action button of a feed message, as yourself | `chat_feed_press` | | PUT | `/api/v1/chat/messages/{message}/bookmark` | Save a message for later, or take the bookmark back (remove: true) | `chat_bookmark_set` | **/chat/search** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/search` | Search messages in the channels you can read | `chat_message_search` | **/chat/dms** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/chat/dms` | Open a DM or group message | `chat_dm_open` | **/chat/unread** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/unread` | Channels with unread messages or mentions | `chat_unread_list` | **/chat/members** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/members` | People and agents you can mention or message | `chat_member_list` | **/chat/agent-actions** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/chat/agent-actions/{action}` | Confirm or decline a write the Venom agent proposed; confirming runs it as you | `chat_agent_action_decide` | **/chat/keywords** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/keywords` | Your keyword alerts | `chat_keyword_list` | | PUT | `/api/v1/chat/keywords` | Add or remove keyword alerts | `chat_keyword_set` | **/chat/bookmarks** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/bookmarks` | The messages you saved for later | `chat_bookmark_list` | **/chat/files** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/chat/files` | Upload a file (base64) to attach to a message | `chat_file_upload` | **/chat/changes** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/chat/changes` | Chat changes after a cursor | `chat_change_list` | ## MCP tools {#tools} 32 tools: 13 read, 19 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `chat_agent_action_decide` | Confirm or decline what the agent proposed | write | `chat:write` | `POST /api/v1/chat/agent-actions/{action}` | | `chat_agent_get` | Read a channel's agent setting | read | `chat:read` | `GET /api/v1/chat/channels/{channel}/agent` | | `chat_agent_run` | Stop or re-run an agent reply | write | `chat:write` | `POST /api/v1/chat/messages/{message}/agent-run` | | `chat_agent_set` | Set a channel's agent | write | `chat:write` | `PUT /api/v1/chat/channels/{channel}/agent` | | `chat_bookmark_list` | List your bookmarks | read | `chat:read` | `GET /api/v1/chat/bookmarks` | | `chat_bookmark_set` | Save a message for later | write | `chat:write` | `PUT /api/v1/chat/messages/{message}/bookmark` | | `chat_change_list` | Follow chat changes | read | `chat:read` | `GET /api/v1/chat/changes` | | `chat_channel_archive` | Archive a channel | write | `chat:write` | `DELETE /api/v1/chat/channels/{channel}` | | `chat_channel_create` | Create a channel | write | `chat:write` | `POST /api/v1/chat/channels` | | `chat_channel_get` | Read a channel | read | `chat:read` | `GET /api/v1/chat/channels/{channel}` | | `chat_channel_join` | Join a channel | write | `chat:write` | `POST /api/v1/chat/channels/{channel}/join` | | `chat_channel_leave` | Leave a channel | write (destructive) | `chat:write` | `POST /api/v1/chat/channels/{channel}/leave` | | `chat_channel_list` | List channels | read | `chat:read` | `GET /api/v1/chat/channels` | | `chat_channel_read` | Mark a channel read | write | `chat:write` | `POST /api/v1/chat/channels/{channel}/read` | | `chat_channel_update` | Change a channel | write | `chat:write` | `PATCH /api/v1/chat/channels/{channel}` | | `chat_dm_open` | Open a DM | write | `chat:write` | `POST /api/v1/chat/dms` | | `chat_feed_list` | List a channel's product feeds | read | `chat:read` | `GET /api/v1/chat/channels/{channel}/feeds` | | `chat_feed_press` | Press a feed message's button | write | `chat:write` | `POST /api/v1/chat/messages/{message}/actions` | | `chat_feed_set` | Set a channel's product feed | write | `chat:write` | `PUT /api/v1/chat/channels/{channel}/feeds` | | `chat_file_upload` | Upload a file to attach | write | `chat:write` | `POST /api/v1/chat/files` | | `chat_keyword_list` | List your keyword alerts | read | `chat:read` | `GET /api/v1/chat/keywords` | | `chat_keyword_set` | Change your keyword alerts | write | `chat:write` | `PUT /api/v1/chat/keywords` | | `chat_member_list` | List members | read | `chat:read` | `GET /api/v1/chat/members` | | `chat_message_create` | Post a message | write | `chat:write` | `POST /api/v1/chat/channels/{channel}/messages` | | `chat_message_delete` | Delete a message | write (destructive) | `chat:write` | `DELETE /api/v1/chat/messages/{message}` | | `chat_message_list` | Read a channel's messages | read | `chat:read` | `GET /api/v1/chat/channels/{channel}/messages` | | `chat_message_react` | React to a message | write | `chat:write` | `POST /api/v1/chat/messages/{message}/reactions` | | `chat_message_search` | Search messages | read | `chat:read` | `GET /api/v1/chat/search` | | `chat_message_update` | Edit or pin a message | write | `chat:write` | `PATCH /api/v1/chat/messages/{message}` | | `chat_pullrequest_get` | Read a pull request card's files | read | `chat:read` | `GET /api/v1/chat/messages/{message}/pull-request` | | `chat_thread_get` | Read a thread | read | `chat:read` | `GET /api/v1/chat/threads/{message}` | | `chat_unread_list` | What did I miss | read | `chat:read` | `GET /api/v1/chat/unread` | ## Related {#related} - [Venom Chat](/docs/cloud/chat.md): channels, threads, unread, search, files and keyword alerts. - [The Venom agent in channels](/docs/cloud/chat-agents.md) and [Product feeds](/docs/cloud/chat-feeds.md). - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Venom Incidents URL: https://cloud.usevenom.dev/docs/developers/incidents Description: Triage errors, run incidents and manage on-call from code or an agent. Read and resolve error issues, declare and update incidents, page people and change alert rules over REST or MCP, and send errors from your apps with an SDK key. Venom Incidents groups your apps' errors into issues, runs incidents with a timeline, and pages whoever is on call. Everything the app does is also an MCP tool and a route of the Incidents API under `/incidents/api/v1`. Your apps send errors to `/incidents/sdk/events` with an environment's SDK key. ## What you can build {#build} - **A triage agent.** List open issues by count (`incidents_error_list`), read the top one with its stack, release and the flags that were served (`incidents_error_get`), then assign or resolve it (`incidents_error_update`, `PATCH /incidents/api/v1/errors/{id}`). - **Incidents from your own tooling.** Declare one from a chat command or a monitor (`POST /incidents/api/v1/incidents`), link the error issues and the fix commit (`POST /incidents/api/v1/incidents/{ref}/links`) and post status updates that also show on the status page (`POST /incidents/api/v1/incidents/{ref}/updates` with `public: true`). - **Release tracking from CI.** Record each deploy (`POST /incidents/api/v1/releases`) and upload source maps for it (`POST /incidents/api/v1/releases/{version}/artifacts`), so stacks are mapped and a spike is tied to the release. - **Pages from any monitor.** Add an alert source (`incidents_oncall_source_create`) and point Alertmanager, Grafana or any JSON sender at `POST /incidents/api/v1/inbound/{id}`. - **On-call from your HR or calendar system.** Read who is on call (`incidents_oncall_who`), cover a shift (`incidents_oncall_override`) or replace a whole schedule (`incidents_oncall_schedule_set`). - **Rollback from an agent.** Rank what changed before the spike (`incidents_incident_implicate`) and undo the top flag change as an audited Flags revert (`incidents_incident_rollback`). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/incidents`, server name `venom-incidents` | | Connect | `claude mcp add --transport http venom-incidents https://cloud.usevenom.dev/workspace/mcp/incidents` | | MCP tools | 56 (24 read, 32 write) | | OAuth scopes | `incidents:read` `incidents:write` `incidents:admin` | | REST twin | 60 routes under `https://cloud.usevenom.dev/api/v1` | | Incidents API | 51 operations | | Webhook events | `errors.issue.created`, `errors.issue.regressed`, `errors.alert.fired`, `incidents.created`, `incidents.updated`, `incidents.resolved`, `incidents.page` | Incidents also serves the same tools at `$VENOM_CLOUD/incidents/mcp` (server `venom-incidents`), its original endpoint. Both take the same credentials. ## Authentication and scopes {#scopes} Incidents has three permissions: `incidents:read`, `incidents:write` and `incidents:admin`. What a caller gets depends on the credential: - A **personal API key** acts with its member's org role. Owners and admins get all three; developers get read and write; billing members and viewers read only. - A **team key** has no member. It gets `incidents:read` and `incidents:write`, so a CI job or an agent can change issues and incidents, but never `incidents:admin`. - An **OAuth app** gets the member's role narrowed to the scopes granted. `incidents:admin` is a separate scope the app must ask for. - An **SDK key** (`vfs_…` server, `vfm_…` mobile) or a **client id** (`vfc_…`) belongs to a Venom Flags environment. It only sends events to `/incidents/sdk/events`; it reads nothing. `incidents:admin` is checked by the service, not by the tool's listed scope, so a tool shown as `incidents:write` in the table below may still answer `This needs the incidents:admin permission`. These need it: | What | MCP tools | REST | |---|---|---| | Alert rules: create, replace, delete | `incidents_alert_set` (except `test: true`), `incidents_alert_delete` | `POST`, `PUT`, `DELETE /incidents/api/v1/alerts…` | | Fingerprint rules: create, delete | `incidents_rule_create`, `incidents_rule_delete` | `POST /incidents/api/v1/rules`, `DELETE /incidents/api/v1/rules/{id}` | | The incident loop's settings | `incidents_setting_update` | `PUT /incidents/api/v1/settings` | | On-call schedules and escalation policies: create, replace, delete | `incidents_oncall_schedule_set`, `incidents_oncall_schedule_delete`, `incidents_oncall_policy_set`, `incidents_oncall_policy_delete` | `/incidents/api/v1/oncall/schedules…`, `/incidents/api/v1/oncall/policies…` | | Alert sources: list, create, change, delete | `incidents_oncall_source_list`, `incidents_oncall_source_create`, `incidents_oncall_source_update`, `incidents_oncall_source_delete` | `/incidents/api/v1/oncall/sources…` | Covering a shift, paging, acknowledging and escalating need only `incidents:write`. The GitHub write token for reproducer PRs is set only by an owner or admin in person (`PUT /incidents/api/v1/github-token`); any agent is refused, and `incidents_github_token_get` only says whether one is set. Other rules: - **The add-on.** Without Venom Incidents on the org, the MCP handshake works and every tool call answers that the add-on is needed. REST answers `403 addon_required`. `GET /incidents/api/v1/me` reports the caller's permissions and whether the org has it. - **Naming the agent.** A key may send `x-venom-agent: daemon:` or `session:` to record the change under one of the org's daemons or sessions. It grants nothing extra. Changes made over MCP are recorded with the agent's name and "via mcp". - **Rate limits.** The REST API answers at most 600 requests a minute per credential; `/incidents/mcp` 240 tool calls a minute. Over the limit is `429` with `retry-after`. - **Agents are never the commander.** An incident opened by an agent has no commander unless the call names a person. ## Worked example {#example} Declare a SEV2 for the `web` project, link the error issue behind it, and post a public status update: ```bash curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"title": "Checkout errors after 1.4.2", "severity": 2, "projects": ["web"], "environments": ["production"]}' curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents/INC-12/links" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"kind": "error_issue", "ref": ""}' curl -X POST "$VENOM_CLOUD/incidents/api/v1/incidents/INC-12/updates" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"body": "We found the cause and are rolling back.", "status": "identified", "public": true}' ``` The first call answers `201` with `{"incident": {...}}`; use its number as `ref` (`12`, `INC-12` or the id). The same over MCP, from a client connected to `/workspace/mcp/incidents`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "incidents_incident_open", "arguments": { "title": "Checkout errors after 1.4.2", "severity": 2, "projects": ["web"], "environments": ["production"] } } } ``` ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "incidents_link_create", "arguments": { "ref": "INC-12", "links": [{ "kind": "error_issue", "ref": "" }] } } } ``` ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "incidents_update_create", "arguments": { "ref": "INC-12", "body": "We found the cause and are rolling back.", "status": "identified", "public": true } } } ``` ## A triage loop {#triage} 1. `incidents_error_list` with `state: "open"` and `sort: "count"`. 2. `incidents_error_get` on the top one: read the culprit, the release it started in and the flags served. 3. If every event had the same flag value, the cause is probably that flag: look it up with the [Flags tools](/docs/developers/flags.md). 4. `incidents_error_update` with `assignee: "agent:triage"`, or `state: "resolved"` and `resolveNext: true` once a fix is merged. A version conflict (`409 version_conflict`, or a tool error saying the issue changed) means someone changed it since you read it: call `incidents_error_get` again and retry with the new `expectVersion`. Over REST, send the version as `If-Match: ""`. ## Tool notes {#tool-notes} What the tools' arguments mean, beyond their input schemas: - **Answers.** Every tool takes `format: "json"` for a structured result; the default is compact markdown. An issue's stack shows in-app frames first, at most 12 by default, source-mapped when the release has maps. - **`incidents_error_list`.** `state` is `open` (default), `all`, `unresolved`, `resolved`, `ignored` or `regressed`. Filter by `project`, `env`, `release`, `assignee` (a member uid, `agent:`, `none` or `me`) or `q`; page with `cursor`. - **`incidents_error_update`.** `state` resolved (with `resolvedIn` or `resolveNext`), ignored (with `ignoreCount` or `ignoreUntil`) or unresolved; `assignee`; or `mergeInto`. Pass `expectVersion` from `incidents_error_get`. - **`incidents_incident_get`.** `since` is a timeline cursor from an earlier answer, so a loop reads only what is new. - **`incidents_incident_update`.** Changes `status`, `severity`, `title`, `summary` and roles; `update` posts a status update (`publish: true` also shows it on the status page), `note` an internal note, and `linkKind` with `link` adds one link. `expectVersion` guards it. - **`incidents_incident_implicate`.** Ranks Flags changes (by timing, and by how much of the sampled errors were served one variation compared with its share of evaluations) and releases, each with a confidence and why. - **`incidents_incident_rollback`.** Undoes a flag change as a normal, audited Flags revert. With `ref`, the incident's top flag (or `flag`, `auditId`); without it, `project`, `flag`, `auditId` and `env`. Where the environment needs approvals it files a request to turn the flag off instead. - **`incidents_incident_postmortem`.** Writes the blameless postmortem into Notes, or returns the one that exists. `ai: true` drafts the prose; `fileActions: true` files its action items in Tasks. - **`incidents_alert_set`.** Creates a rule (no `id`), replaces one (`id` with `expectVersion`), dry-runs one over the last 24 hours (`test: true`, nothing recorded) or deletes one (`delete: true`). - **`incidents_oncall_schedule_set`.** Creates or replaces a schedule with its rotations; a rotation names members or an org team. `incidents_oncall_schedule_get` with `from` and `to` adds the timeline. - **`incidents_oncall_source_create`.** Returns the source's webhook secret once. Store it in the monitor and never log it. - **`incidents_reproducer_write`.** Writes a failing test and opens it as a draft PR on `venom/reproducer-`. It needs the org's GitHub write token and says so when there is none. - **`incidents_eval_case_draft`.** Drafts an eval task from the incident's linked fix or revert commit for a person to review. It runs nothing. ## Sending errors from your apps {#sdk} `POST /incidents/sdk/events` takes one event, a list of up to 100, or `{"events": [...], "release": {...}}`, at most 200 KB, with `Authorization: Bearer vfs_…` (or `vfm_…`) or `x-venom-client-id: vfc_…`. It answers `202 {"accepted", "rejected", "ids"}`. The SDKs, the event fields and the limits are in [Error SDKs](/docs/incidents/errors-sdk.md); a Sentry DSN can point here too ([Migrate from Sentry](/docs/incidents/migrate-from-sentry.md)). ## Events {#events} 7 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `errors.issue.created` | A new error issue appeared in Venom Incidents (id, project, title, count and release; never the event itself). | | `errors.issue.regressed` | A resolved error issue happened again in Venom Incidents. | | `errors.alert.fired` | One of the org's error alert rules fired (rule, kind, issue, the numbers behind it, and the action). | | `incidents.created` | An incident was declared in Venom Incidents (number, title, severity, status, projects; never its notes). | | `incidents.updated` | An incident's status, severity, roles or title changed. | | `incidents.resolved` | An incident was resolved. | | `incidents.page` | Someone is being paged: the page, its title, the escalation level and the members told (so an org can bridge SMS or voice through its own gateway). Sent again at each escalation. | Two more ways in, beyond org webhooks: - **Alert sources** take alerts in: `POST /incidents/api/v1/inbound/{id}`, authenticated by the source's secret as a bearer token or an `X-Venom-Signature` HMAC of the body. Firing pages the policy and may open an incident; resolved resolves the page. See [Alert sources](/docs/incidents/alert-sources.md). - **Public status updates** (`public: true`) reach the status page's subscribers as `status.incident.*` deliveries. See [Build on the Status page](/docs/developers/status.md). ## REST routes {#rest} The REST twin: 60 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/incidents/errors` | Error groups, filtered by project, environment, release, state, assignee or text | `incidents_error_list` | | POST | `/api/v1/incidents/errors/split` | Split merged error groups back apart | `incidents_error_split` | | GET | `/api/v1/incidents/errors/{id}` | One error group with its latest (or a chosen) event | `incidents_error_get` | | PATCH | `/api/v1/incidents/errors/{id}` | Resolve, ignore, reopen, assign or merge an error group | `incidents_error_update` | | GET | `/api/v1/incidents/errors/{id}/events` | An error group's events, newest first | `incidents_event_list` | | GET | `/api/v1/incidents/errors/{id}/events/{event}` | One event of an error group, with its stack | `incidents_event_get` | | POST | `/api/v1/incidents/errors/{into}/merge` | Merge other error groups into this one | `incidents_error_merge` | | POST | `/api/v1/incidents/errors/{id}/tasks-issue` | File a Venom Tasks issue for an error group | `incidents_error_file` | | GET | `/api/v1/incidents/alerts` | Error alert rules, with recent hits | `incidents_alert_list` | | POST | `/api/v1/incidents/alerts` | Add an error alert rule | `incidents_alert_set` | | DELETE | `/api/v1/incidents/alerts` | Delete error alert rules by id (ids=a,b) | `incidents_alert_delete` | | GET | `/api/v1/incidents/alerts/hits` | When alert rules fired | `incidents_alert_hit_list` | | POST | `/api/v1/incidents/alerts/test` | What an alert rule would have fired on, without saving it | `incidents_alert_test` | | PUT | `/api/v1/incidents/alerts/{id}` | Change, test or delete an error alert rule | `incidents_alert_set` | | GET | `/api/v1/incidents/incidents` | Incidents, open first | `incidents_incident_list` | | POST | `/api/v1/incidents/incidents` | Open an incident | `incidents_incident_open` | | GET | `/api/v1/incidents/incidents/{ref}` | One incident with its timeline | `incidents_incident_get` | | PATCH | `/api/v1/incidents/incidents/{ref}` | Change an incident: status, severity, roles, an update, a link or a note | `incidents_incident_update` | | GET | `/api/v1/incidents/incidents/{ref}/implicate` | The changes (deploys, flags) most likely behind an incident, ranked | `incidents_incident_implicate` | | POST | `/api/v1/incidents/incidents/{ref}/rollback` | Roll back the flag change behind an incident | `incidents_incident_rollback` | | POST | `/api/v1/incidents/incidents/{ref}/postmortem` | Draft an incident's postmortem (optionally filing its action items) | `incidents_incident_postmortem` | | GET | `/api/v1/incidents/incidents/{ref}/eval-case` | An incident's eval case | `incidents_eval_case_get` | | POST | `/api/v1/incidents/incidents/{ref}/eval-case` | Draft an eval case from an incident | `incidents_eval_case_draft` | | GET | `/api/v1/incidents/incidents/{ref}/reproducer` | An incident's reproducer | `incidents_reproducer_get` | | POST | `/api/v1/incidents/incidents/{ref}/reproducer` | Write a reproducer for an incident | `incidents_reproducer_write` | | POST | `/api/v1/incidents/incidents/{ref}/links` | Link errors, issues or other things to an incident | `incidents_link_create` | | DELETE | `/api/v1/incidents/incidents/{ref}/links` | Remove a link from an incident | `incidents_link_delete` | | POST | `/api/v1/incidents/incidents/{ref}/updates` | Post an update on an incident (public: on the status page) | `incidents_update_create` | | POST | `/api/v1/incidents/rollback` | Roll back a flag change by flag or audit id, without an incident | `incidents_incident_rollback` | | GET | `/api/v1/incidents/projects` | The org's error-tracking projects | `incidents_project_list` | | GET | `/api/v1/incidents/settings` | The incident loop's settings per project | `incidents_setting_get` | | PUT | `/api/v1/incidents/settings` | Set a project's incident loop: auto-rollback, threshold, team, triage agent, postmortems | `incidents_setting_update` | | GET | `/api/v1/incidents/rules` | A project's grouping rules | `incidents_rule_list` | | POST | `/api/v1/incidents/rules` | Add a grouping rule | `incidents_rule_create` | | DELETE | `/api/v1/incidents/rules` | Delete grouping rules by id (ids=a,b) | `incidents_rule_delete` | | GET | `/api/v1/incidents/releases` | A project's releases | `incidents_release_list` | | POST | `/api/v1/incidents/releases` | Record a release or deploy | `incidents_release_create` | | GET | `/api/v1/incidents/releases/{version}/artifacts` | A release's source maps and debug files | `incidents_artifact_list` | | GET | `/api/v1/incidents/github-token` | Whether a GitHub token is set for reproducers (never the token) | `incidents_github_token_get` | | GET | `/api/v1/incidents/oncall/now` | Who is on call now, and open pages | `incidents_oncall_who` | | GET | `/api/v1/incidents/oncall/members` | Members who can be put on call | `incidents_oncall_member_list` | | GET | `/api/v1/incidents/oncall/schedules` | On-call schedules | `incidents_oncall_schedule_list` | | POST | `/api/v1/incidents/oncall/schedules` | Create an on-call schedule | `incidents_oncall_schedule_set` | | GET | `/api/v1/incidents/oncall/schedules/{schedule}` | A schedule, optionally with its timeline | `incidents_oncall_schedule_get` | | PUT | `/api/v1/incidents/oncall/schedules/{id}` | Replace a schedule (send it whole) | `incidents_oncall_schedule_set` | | DELETE | `/api/v1/incidents/oncall/schedules/{id}` | Delete a schedule | `incidents_oncall_schedule_delete` | | POST | `/api/v1/incidents/oncall/schedules/{schedule}/overrides` | Put someone on call for a while instead | `incidents_oncall_override` | | PATCH | `/api/v1/incidents/oncall/overrides/{id}` | Move an override or change who covers it | `incidents_oncall_override_move` | | DELETE | `/api/v1/incidents/oncall/overrides/{id}` | Delete an override | `incidents_oncall_override_delete` | | GET | `/api/v1/incidents/oncall/policies` | Escalation policies | `incidents_oncall_policy_list` | | POST | `/api/v1/incidents/oncall/policies` | Create an escalation policy | `incidents_oncall_policy_set` | | PUT | `/api/v1/incidents/oncall/policies/{id}` | Replace an escalation policy (send it whole) | `incidents_oncall_policy_set` | | DELETE | `/api/v1/incidents/oncall/policies/{id}` | Delete an escalation policy | `incidents_oncall_policy_delete` | | POST | `/api/v1/incidents/oncall/pages` | Page whoever is on call | `incidents_oncall_page_create` | | POST | `/api/v1/incidents/oncall/pages/{page}/ack` | Acknowledge a page (resolve: true resolves it) | `incidents_oncall_ack` | | POST | `/api/v1/incidents/oncall/pages/{page}/escalate` | Escalate a page to the next level now | `incidents_oncall_page_escalate` | | GET | `/api/v1/incidents/oncall/sources` | Inbound alert sources (never their secrets) | `incidents_oncall_source_list` | | POST | `/api/v1/incidents/oncall/sources` | Add an alert source webhook (its secret is in the answer once) | `incidents_oncall_source_create` | | PATCH | `/api/v1/incidents/oncall/sources/{id}` | Enable or disable an alert source, or change its policy or severity | `incidents_oncall_source_update` | | DELETE | `/api/v1/incidents/oncall/sources/{id}` | Delete an alert source | `incidents_oncall_source_delete` | Also the Incidents API: 51 operations, generated from `services/nodejs-cloud/contracts/incidents-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. **/me** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/me` | Who is calling | key or token | **/projects** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/projects` | Venom Flags' projects with their environments. | key or token | **/errors** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/errors` | List error issues. | key or token | | GET | `/incidents/api/v1/errors/{id}` | An issue with its counts, releases, tags, flags served, merged issues and activity. | key or token | | PATCH | `/incidents/api/v1/errors/{id}` | Resolve, ignore, reopen or assign. | key or token | | GET | `/incidents/api/v1/errors/{id}/events` | The issue's stored events | key or token | | GET | `/incidents/api/v1/errors/{id}/events/{event}` | One event | key or token | | POST | `/incidents/api/v1/errors/{id}/merge` | Merge other issues of the project into this one. | key or token | | POST | `/incidents/api/v1/errors/{id}/split` | Give a merged issue its own fingerprint and count back. | key or token | | POST | `/incidents/api/v1/errors/{id}/tasks-issue` | File the issue into Venom Tasks with the stack, release and flags; stores the link. | key or token | **/releases** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/releases` | A project's releases. | key or token | | POST | `/incidents/api/v1/releases` | Announce a release from CI. | key or token | | GET | `/incidents/api/v1/releases/{version}/artifacts` | The release's source maps. | key or token | | POST | `/incidents/api/v1/releases/{version}/artifacts` | Upload a source map for one generated file. The body is the map (gzip with Content-Encoding for more than 4 MB). | key or token | **/rules** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/rules` | A project's fingerprint rules. | key or token | | POST | `/incidents/api/v1/rules` | Add a fingerprint rule (incidents:admin). | key or token | | DELETE | `/incidents/api/v1/rules/{id}` | Remove a fingerprint rule (incidents:admin). | key or token | **/alerts** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/alerts` | A project's error alert rules. | key or token | | POST | `/incidents/api/v1/alerts` | Create an alert rule (incidents:admin). kind is new_issue, regression, spike, threshold or slo_burn. | key or token | | PUT | `/incidents/api/v1/alerts/{id}` | Replace an alert rule (incidents:admin). | key or token | | DELETE | `/incidents/api/v1/alerts/{id}` | Delete an alert rule (incidents:admin). | key or token | | POST | `/incidents/api/v1/alerts/test` | What a rule would have fired in the last 24 hours. Nothing is recorded or sent. | key or token | | GET | `/incidents/api/v1/alerts/hits` | Recent alert hits. | key or token | | POST | `/incidents/api/v1/alerts/seen` | Mark the bell's alert hits as seen for the caller. | key or token | **/incidents** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/incidents` | List incidents, worst severity first. | key or token | | POST | `/incidents/api/v1/incidents` | Declare an incident. The opener becomes the commander unless an agent opens it. | key or token | | GET | `/incidents/api/v1/incidents/{ref}` | An incident with its links and timeline. | key or token | | PATCH | `/incidents/api/v1/incidents/{ref}` | Change status, severity, title, summary, projects, environments or a role. A status change is a timeline entry. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/updates` | Post a status update (kind status_update, may move the status; public shows it on the status page) or an internal note. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/links` | Link an error issue (id), a flag (project/key), a release (version) or a Tasks issue (key). | key or token | | DELETE | `/incidents/api/v1/incidents/{ref}/links` | Remove a link. | key or token | | GET | `/incidents/api/v1/incidents/{ref}/implicate` | Rank what changed before the incident's error spike (Flags changes and releases), each with a confidence and the evidence. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/rollback` | Roll back the top-ranked flag change (or the one named by flag or auditId) as a normal Flags revert. Where the environment needs approvals, files a request to turn the flag off. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/postmortem` | Write the incident's blameless postmortem into Venom Notes (or return the existing one). ai drafts the prose with the org's model; fileActions files the note's unchecked action items in Tasks. | key or token | | GET | `/incidents/api/v1/incidents/{ref}/eval-case` | The eval case drafted from the regression behind the incident (VEN-246), or draft null with a reason. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/eval-case` | Draft it, or draft it again, from the incident's linked fix or revert commit, or the merged pull requests and commits on its Tasks issue. A draft for a person to review; nothing runs an eval or calls a model. 200 with a reason and no draft when nothing is linked. Needs incidents:write. | key or token | | GET | `/incidents/api/v1/incidents/{ref}/reproducer` | The incident's reproducer runs (VEN-246, ADR 0076), newest first, with each draft PR's CI outcome as the GitHub webhook reports it. | key or token | | POST | `/incidents/api/v1/incidents/{ref}/reproducer` | Write a failing test with the org's own model and open it as a draft pull request on a new branch venom/reproducer-, through the org's GitHub write token. New test files only (never under .github/ or outside the repository). One run at a time per incident, a daily cap. Needs incidents:write. 409 no_github_token (no token set), no_repo, reproducer_running or branch_exists; 422 reproducer_refused (a proposed file failed the path checks; nothing was written); 429 reproducer_cap. | key or token | | POST | `/incidents/sdk/events` | Send one event, a list of up to 100, or {events, release}. 200 KB at most. | SDK key or client id | **/rollback** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/incidents/api/v1/rollback` | Undo a Flags change with no incident behind it, and write a short postmortem. | key or token | **/github-token** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/github-token` | Whether the org's GitHub write token for reproducer PRs is set (its last four characters and the default repository; never the token). | key or token | | PUT | `/incidents/api/v1/github-token` | Save or replace the token (a fine-grained personal access token with Contents and Pull requests read and write), sealed in the vault, and the default repository. An owner or admin in person; agents are refused. | key or token | | DELETE | `/incidents/api/v1/github-token` | Remove the token. An owner or admin in person. | key or token | **/settings** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/settings` | The loop's settings per project and environment (automatic rollback, confidence, the Tasks team and triage agent, postmortems). | key or token | | PUT | `/incidents/api/v1/settings` | Change them for a project (env empty) or an environment. Needs incidents:admin. Automatic rollback is off until set. | key or token | **/oncall** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/incidents/api/v1/oncall/{path}` | Read on-call. now (who is on call), members, schedules, schedules/{id}/timeline?from=&to= (segments), policies, pages?status=, sources (admin). | key or token | | POST | `/incidents/api/v1/oncall/{path}` | Create or act. schedules (name, tz, rotations[{members, startDate, handoff, lengthDays, layer, restriction}]), schedules/{id}/overrides (member, startAt, endAt), policies (name, levels[{targets, delayMin}], repeat, slackChannel, isDefault), pages (title, policy), pages/{id}/ack\|resolve\|escalate, sources (name, kind, escalationId, openIncident; the secret is returned once). | key or token | | PUT | `/incidents/api/v1/oncall/{path}` | Replace a schedule (schedules/{id}) or a policy (policies/{id}); If-Match names the version. | key or token | | PATCH | `/incidents/api/v1/oncall/{path}` | Turn a source on or off, or change what it opens (sources/{id}); move an override to a new window, optionally to someone else (overrides/{id} with startAt, endAt, member?). | key or token | | DELETE | `/incidents/api/v1/oncall/{path}` | Delete a schedule, override, policy or source. | key or token | **/inbound** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/incidents/api/v1/inbound/{id}` | Alerts from Alertmanager, Grafana or any JSON sender. Authenticated by the source's secret (Authorization Bearer, or X-Venom-Signature sha256=HMAC of the body, optionally with X-Venom-Timestamp). Firing pages the policy and may open an incident; resolved resolves the page. | none | The on-call routes are one catch-all, `/incidents/api/v1/oncall/{path}`: `now`, `members`, `schedules`, `schedules/{id}`, `schedules/{id}/timeline`, `schedules/{id}/overrides`, `overrides/{id}`, `policies`, `policies/{id}`, `pages`, `pages/{id}/ack`, `pages/{id}/resolve`, `pages/{id}/escalate`, `sources` and `sources/{id}`. See [On-call](/docs/incidents/on-call.md#rest). Every Incidents tool also has a route on the workspace REST twin, under `/api/v1/incidents` with the same paths (`GET /api/v1/incidents/errors`, `PATCH /api/v1/incidents/incidents/{ref}`, `GET /api/v1/incidents/oncall/now` and so on). It takes the credentials `/workspace/mcp` takes, an OAuth token for the workspace included, and a request becomes the tool's arguments by name (camelCase, as the tools take them). `If-Match` fills `expectVersion`. A few twin routes take a list in place of a path id: `POST /api/v1/incidents/errors/split` (`ids`), `DELETE /api/v1/incidents/alerts` and `DELETE /api/v1/incidents/rules` (`?ids=a,b`). See [REST](/docs/developers/rest.md). ## MCP tools {#tools} 56 tools: 24 read, 32 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `incidents_alert_delete` | Delete error alert rules | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/alerts` | | `incidents_alert_hit_list` | List alert hits | read | `incidents:read` | `GET /api/v1/incidents/alerts/hits` | | `incidents_alert_list` | List error alert rules | read | `incidents:read` | `GET /api/v1/incidents/alerts` | | `incidents_alert_set` | Create, change, test or delete an error alert rule | write | `incidents:admin` | `POST /api/v1/incidents/alerts` (+1) | | `incidents_alert_test` | Dry-run an alert rule | read | `incidents:read` | `POST /api/v1/incidents/alerts/test` | | `incidents_artifact_list` | List a release's source maps | read | `incidents:read` | `GET /api/v1/incidents/releases/{version}/artifacts` | | `incidents_error_file` | File an error issue into Tasks | write | `incidents:write` | `POST /api/v1/incidents/errors/{id}/tasks-issue` | | `incidents_error_get` | Read an error issue | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}` | | `incidents_error_list` | List error issues | read | `incidents:read` | `GET /api/v1/incidents/errors` | | `incidents_error_merge` | Merge error issues | write | `incidents:write` | `POST /api/v1/incidents/errors/{into}/merge` | | `incidents_error_split` | Split a merged error issue | write | `incidents:write` | `POST /api/v1/incidents/errors/split` | | `incidents_error_update` | Resolve, ignore, assign or merge an error issue | write | `incidents:write` | `PATCH /api/v1/incidents/errors/{id}` | | `incidents_eval_case_draft` | Draft an eval case from an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/eval-case` | | `incidents_eval_case_get` | Read an incident's eval case draft | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/eval-case` | | `incidents_event_get` | Read one error event | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}/events/{event}` | | `incidents_event_list` | List an error issue's events | read | `incidents:read` | `GET /api/v1/incidents/errors/{id}/events` | | `incidents_github_token_get` | Is a GitHub write token set for reproducers | read | `incidents:read` | `GET /api/v1/incidents/github-token` | | `incidents_incident_get` | Read an incident | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}` | | `incidents_incident_implicate` | What changed before the spike | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/implicate` | | `incidents_incident_list` | List incidents | read | `incidents:read` | `GET /api/v1/incidents/incidents` | | `incidents_incident_open` | Declare an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents` | | `incidents_incident_postmortem` | Write the postmortem | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/postmortem` | | `incidents_incident_rollback` | Roll back the implicated flag | write (destructive) | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/rollback` (+1) | | `incidents_incident_update` | Update an incident | write | `incidents:write` | `PATCH /api/v1/incidents/incidents/{ref}` | | `incidents_link_create` | Link things to an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/links` | | `incidents_link_delete` | Unlink from an incident | write (destructive) | `incidents:write` | `DELETE /api/v1/incidents/incidents/{ref}/links` | | `incidents_oncall_ack` | Acknowledge a page | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages/{page}/ack` | | `incidents_oncall_member_list` | List members to put on call | read | `incidents:read` | `GET /api/v1/incidents/oncall/members` | | `incidents_oncall_override` | Cover a shift | write | `incidents:write` | `POST /api/v1/incidents/oncall/schedules/{schedule}/overrides` | | `incidents_oncall_override_delete` | Remove a shift cover | write (destructive) | `incidents:write` | `DELETE /api/v1/incidents/oncall/overrides/{id}` | | `incidents_oncall_override_move` | Move a shift cover | write | `incidents:write` | `PATCH /api/v1/incidents/oncall/overrides/{id}` | | `incidents_oncall_page_create` | Page the on-call | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages` | | `incidents_oncall_page_escalate` | Escalate a page now | write | `incidents:write` | `POST /api/v1/incidents/oncall/pages/{page}/escalate` | | `incidents_oncall_policy_delete` | Delete an escalation policy | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/policies/{id}` | | `incidents_oncall_policy_list` | List escalation policies | read | `incidents:read` | `GET /api/v1/incidents/oncall/policies` | | `incidents_oncall_policy_set` | Create or replace an escalation policy | write | `incidents:admin` | `POST /api/v1/incidents/oncall/policies` (+1) | | `incidents_oncall_schedule_delete` | Delete an on-call schedule | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/schedules/{id}` | | `incidents_oncall_schedule_get` | Read an on-call schedule | read | `incidents:read` | `GET /api/v1/incidents/oncall/schedules/{schedule}` | | `incidents_oncall_schedule_list` | List on-call schedules | read | `incidents:read` | `GET /api/v1/incidents/oncall/schedules` | | `incidents_oncall_schedule_set` | Create or replace an on-call schedule | write | `incidents:admin` | `POST /api/v1/incidents/oncall/schedules` (+1) | | `incidents_oncall_source_create` | Add an alert source | write | `incidents:admin` | `POST /api/v1/incidents/oncall/sources` | | `incidents_oncall_source_delete` | Delete an alert source | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/oncall/sources/{id}` | | `incidents_oncall_source_list` | List alert sources | read | `incidents:admin` | `GET /api/v1/incidents/oncall/sources` | | `incidents_oncall_source_update` | Change an alert source | write | `incidents:admin` | `PATCH /api/v1/incidents/oncall/sources/{id}` | | `incidents_oncall_who` | Who is on call | read | `incidents:read` | `GET /api/v1/incidents/oncall/now` | | `incidents_project_list` | List projects and environments | read | `incidents:read` | `GET /api/v1/incidents/projects` | | `incidents_release_create` | Record a release | write | `incidents:write` | `POST /api/v1/incidents/releases` | | `incidents_release_list` | List releases | read | `incidents:read` | `GET /api/v1/incidents/releases` | | `incidents_reproducer_get` | Read an incident's reproducer PRs | read | `incidents:read` | `GET /api/v1/incidents/incidents/{ref}/reproducer` | | `incidents_reproducer_write` | Write a reproducer PR for an incident | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/reproducer` | | `incidents_rule_create` | Create a fingerprint rule | write | `incidents:admin` | `POST /api/v1/incidents/rules` | | `incidents_rule_delete` | Delete fingerprint rules | write (destructive) | `incidents:admin` | `DELETE /api/v1/incidents/rules` | | `incidents_rule_list` | List fingerprint rules | read | `incidents:read` | `GET /api/v1/incidents/rules` | | `incidents_setting_get` | Read the incident loop's settings | read | `incidents:read` | `GET /api/v1/incidents/settings` | | `incidents_setting_update` | Change the incident loop's settings | write | `incidents:admin` | `PUT /api/v1/incidents/settings` | | `incidents_update_create` | Post an incident update | write | `incidents:write` | `POST /api/v1/incidents/incidents/{ref}/updates` | ## Related {#related} - [Venom Incidents](/docs/incidents.md), [Error issues](/docs/incidents/errors.md), [Incidents](/docs/incidents/incidents.md), [The loop](/docs/incidents/the-loop.md), [Alerts](/docs/incidents/alerts.md) and [On-call](/docs/incidents/on-call.md). - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks](/docs/developers/webhooks.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on the Status page URL: https://cloud.usevenom.dev/docs/developers/status Description: Manage the public status page from code or an agent. Add uptime checks, read their results, schedule maintenance, edit the listed services and manage subscribers over REST or MCP. The status page publishes uptime for your models and the services you check. Everything its settings page does with checks, maintenance, services and subscribers is also an MCP tool and a REST route. ## What you can build {#build} - **Checks from your deploy pipeline.** Create an `http`, `tcp` or `heartbeat` check for each new service (`POST /api/v1/status/checks`) and delete it when the service goes away. - **Maintenance from your change calendar.** Schedule a window before a planned migration (`POST /api/v1/status/maintenance`), with alerts muted while it runs. - **Uptime reports.** Read a check's runs and its last 24 hours of uptime and latency (`GET /api/v1/status/checks/{check}/results`) into your own dashboard. - **A heartbeat for a nightly job.** Create a `heartbeat` check, keep its secret URL in your job, and have the job request it each time it finishes. - **An agent that keeps the page tidy.** Connect `venom-status` and let an agent list stale checks, rename services and remove subscribers that bounce. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/status`, server name `venom-status` | | Connect | `claude mcp add --transport http venom-status https://cloud.usevenom.dev/workspace/mcp/status` | | MCP tools | 16 (6 read, 10 write) | | OAuth scopes | `status:read` `status:write` | | REST twin | 16 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `status.incident.created`, `status.incident.updated`, `status.incident.resolved`, `status.maintenance.scheduled`, `status.maintenance.started`, `status.maintenance.completed`, `status.component.changed` | ## Authentication and scopes {#scopes} The page's settings belong to the organisation, so the caller's org role decides: - A **personal API key** acts with its member's role. Owners and admins can change things; a viewer can only read. - A **team key** has no member. It reads and is refused every change. - An **OAuth app** needs `status:read` to use the tools at all and `status:write` to change anything, on top of the member's role. A refused write answers `403` over REST, or a tool error that names the missing permission over MCP. ## Worked example {#example} Add a website check that alerts after three failed runs, then read its results: ```bash curl -X POST "$VENOM_CLOUD/api/v1/status/checks" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"name": "Website", "kind": "http", "url": "https://example.com/health", "component": "website", "fail_after": 3}' curl "$VENOM_CLOUD/api/v1/status/checks//results?limit=20" \ -H "Authorization: Bearer $VENOM_API_KEY" ``` The same over MCP, from any client connected to `/workspace/mcp/status`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "status_check_create", "arguments": { "name": "Website", "kind": "http", "url": "https://example.com/health", "component": "website", "fail_after": 3 } } } ``` A `heartbeat` check's answer carries its secret URL once. Store it in your job's secrets and never log it. ## Events {#events} 7 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `status.incident.created` | An incident was published on the org's public status page: its title, impact, status, components and first update, as visitors see them. | | `status.incident.updated` | A published status page incident got an update: its status and the update as posted on the page. | | `status.incident.resolved` | A published status page incident was resolved. | | `status.maintenance.scheduled` | A maintenance window was published on the status page: its title, times and components. | | `status.maintenance.started` | A published maintenance window began. | | `status.maintenance.completed` | A published maintenance window ended. | | `status.component.changed` | A status page component (a model) went down or degraded, or is working again, as its automatic incidents see it: the component, its label, the new status (down, degraded, operational, or idle when it had no traffic) and the incident. | Readers of the page follow it with their own webhooks instead: `POST /api/status/subscribe` with a slug and a URL subscribes one, and it receives `status.incident.*` and `status.maintenance.*` deliveries signed like org webhooks. See [Status page subscribers](/docs/cloud/status-page.md#subscribers). ## REST routes {#rest} The REST twin: 16 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/status/checks** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/status/checks` | List the status page's uptime checks with their current state | `status_check_list` | | POST | `/api/v1/status/checks` | Add an http, tcp or heartbeat check | `status_check_create` | | GET | `/api/v1/status/checks/{check}` | Read an uptime check | `status_check_get` | | PATCH | `/api/v1/status/checks/{check}` | Change, pause or rotate the secret URL of a check | `status_check_update` | | DELETE | `/api/v1/status/checks/{check}` | Delete a check and its results | `status_check_delete` | | GET | `/api/v1/status/checks/{check}/results` | A check's runs, newest first, with the last 24 hours' uptime and latency | `status_check_results` | **/status/maintenance** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/status/maintenance` | List maintenance windows | `status_maintenance_list` | | POST | `/api/v1/status/maintenance` | Schedule a maintenance window | `status_maintenance_create` | | PATCH | `/api/v1/status/maintenance/{maintenance}` | Reschedule, reword, hide or end a window | `status_maintenance_update` | | DELETE | `/api/v1/status/maintenance/{maintenance}` | Delete a maintenance window | `status_maintenance_delete` | **/status/subscribers** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/status/subscribers` | Who follows the status page | `status_subscriber_list` | | DELETE | `/api/v1/status/subscribers/{subscriber}` | Remove a subscriber | `status_subscriber_delete` | **/status/components** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/status/components` | The services the status page lists | `status_component_list` | | POST | `/api/v1/status/components` | List a service on the status page | `status_component_create` | | PATCH | `/api/v1/status/components` | Rename a component or move it to a group | `status_component_update` | | DELETE | `/api/v1/status/components` | Take a service off the status page | `status_component_delete` | The admin API has the same operations under `/api/admin/v1/status-page` for operators who use an admin key ([Status page admin API](/docs/cloud/status-page.md#admin-api)). ## MCP tools {#tools} 16 tools: 6 read, 10 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `status_check_create` | Add an uptime check | write | `status:write` | `POST /api/v1/status/checks` | | `status_check_delete` | Delete an uptime check | write (destructive) | `status:write` | `DELETE /api/v1/status/checks/{check}` | | `status_check_get` | Read an uptime check | read | `status:read` | `GET /api/v1/status/checks/{check}` | | `status_check_list` | List uptime checks | read | `status:read` | `GET /api/v1/status/checks` | | `status_check_results` | Read a check's results | read | `status:read` | `GET /api/v1/status/checks/{check}/results` | | `status_check_update` | Change an uptime check | write | `status:write` | `PATCH /api/v1/status/checks/{check}` | | `status_component_create` | Add a component to the page | write | `status:write` | `POST /api/v1/status/components` | | `status_component_delete` | Remove a page component | write (destructive) | `status:write` | `DELETE /api/v1/status/components` | | `status_component_list` | List status page components | read | `status:read` | `GET /api/v1/status/components` | | `status_component_update` | Change a page component | write | `status:write` | `PATCH /api/v1/status/components` | | `status_maintenance_create` | Schedule maintenance | write | `status:write` | `POST /api/v1/status/maintenance` | | `status_maintenance_delete` | Delete a maintenance window | write (destructive) | `status:write` | `DELETE /api/v1/status/maintenance/{maintenance}` | | `status_maintenance_list` | List maintenance windows | read | `status:read` | `GET /api/v1/status/maintenance` | | `status_maintenance_update` | Change a maintenance window | write | `status:write` | `PATCH /api/v1/status/maintenance/{maintenance}` | | `status_subscriber_delete` | Remove a subscriber | write (destructive) | `status:write` | `DELETE /api/v1/status/subscribers/{subscriber}` | | `status_subscriber_list` | List status page subscribers | read | `status:read` | `GET /api/v1/status/subscribers` | ## Related {#related} - [Status page uptime checks, maintenance and subscribers](/docs/cloud/status-page.md): what each check kind does, limits and troubleshooting. - [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Venom Forms URL: https://cloud.usevenom.dev/docs/developers/forms Description: Build, preview, publish and close forms from code or an agent, read and export their responses, and send each response to Notes, Tasks, Slack, Funnel, Support, Calendar or your own webhook, over REST or MCP. Venom Forms builds forms out of blocks (questions and statements) with stable ids, logic rules and settings. An agent or a script can take a form from an outline to a published link, preview the path some answers take through the logic, and read the responses later. Everything the builder does is a REST operation under `/forms/api/v1` and an MCP tool. Every change is recorded with the caller's name in the form's history, and any change can be reverted. ## What you can build {#build} - **Forms from a short outline.** Send a markdown outline to `POST /forms/api/v1/forms` (or `forms_form_create`) and get a draft with block ids back. - **A check before publishing.** Run sample answers through the logic with `POST /forms/api/v1/forms/{id}/preview` (or `forms_form_preview`); nothing is stored. - **Responses into your own system.** Page through `GET /forms/api/v1/forms/{id}/responses?after=`, follow every form at once with `GET /forms/api/v1/responses?after=`, export CSV from `GET /forms/api/v1/forms/{id}/export`, or add a `webhook` destination and receive `forms.response.created`. - **Responses from your own system.** A signup in your app, a lead from a partner: `POST /forms/api/v1/forms/{id}/responses` with `{answers}` (or `forms_response_create`) stores it as a response, validated and delivered like one from the form's page. - **Lead and support intake.** Connect a form to a Funnel deal, a Support conversation or a Tasks team's Triage with `forms_form_connect`, so each response becomes a record there. - **A weekly summary.** Read counts, completion, choice shares, averages, NPS and drop-off from `GET /forms/api/v1/forms/{id}/summary` (or `forms_response_summary`) and post them where your team reads. - **Delivery monitoring.** Read the delivery log (`forms_delivery_list`) and send failed ones again (`forms_delivery_retry`). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/forms`, server name `venom-forms` | | Connect | `claude mcp add --transport http venom-forms https://cloud.usevenom.dev/workspace/mcp/forms` | | MCP tools | 19 (9 read, 10 write) | | OAuth scopes | `forms:read` `forms:write` | | REST twin | none yet | | Forms API | 23 operations | | Webhook events | `forms.response.created` | The older endpoint `/forms/mcp` still serves the same tools. `/forms/agents` in the app shows the connect commands with your origin filled in. ## Authentication and scopes {#scopes} Forms has two permissions, `forms:read` and `forms:write`, and no admin permission. | Credential | Recorded as | Permissions | |---|---|---| | Personal API key (`vck_…`) | the key's name, `key:` | the member's role: owners, admins and developers read and write; billing and viewer members read | | Team API key | the key's name, `key:` | `forms:read` and `forms:write` | | OAuth app | the app's name, `mcp::` | the member's role, narrowed to the scopes the member granted | - An OAuth token works only on the resource it was issued for: a token for `/workspace/mcp` (or `/workspace/mcp/forms`) works on those endpoints, and only a token for the `forms` resource (`/forms/mcp`) works on `/forms/api/v1`. - A request with an API key can send `x-venom-agent: daemon:` or `session:` to record one of the org's daemons or venom sessions as the actor. It grants nothing beyond the key's own rights. - If the org has not added Forms, each REST call answers `403 addon_required` and each tool says where to add it. `GET /forms/api/v1/me` always answers, with your permissions. - Rate limits per credential: 600 requests a minute on `/forms/api/v1`, 240 a minute on `/forms/mcp`. Past the limit you get `429` with `Retry-After`. - Forms has no SDK keys. Respondents use the public page at `/f/{slug}` or an embed of it ([Share a form](/docs/cloud/forms-sharing.md)). A refused write is `403` over REST, or a tool error in plain words over MCP. ## Worked example {#example} Make a feedback form that asks what went wrong after a low rating, preview a low answer, then publish it: ```bash curl -X POST "$VENOM_CLOUD/forms/api/v1/forms" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"outline": "# Feedback\n- Rating [rating 1-5] *\n- What went wrong? [long text]\nif Rating <= 2 then show What went wrong?"}' curl -X POST "$VENOM_CLOUD/forms/api/v1/forms/frm_…/preview" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"answers": {"": 1}}' curl -X PATCH "$VENOM_CLOUD/forms/api/v1/forms/frm_…" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -H 'If-Match: "1"' \ -d '{"instructions": [{"kind": "publish"}], "comment": "ready for the beta list"}' ``` The create answer has the form's id, its block ids and any outline line it could not read (`warnings`). A new form is at version 1; each answer's `ETag` is the current version, which the next write sends back as `If-Match`. The same create over MCP, from any client connected to `/workspace/mcp/forms`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "forms_form_create", "arguments": { "outline": "# Feedback\n- Rating [rating 1-5] *\n- What went wrong? [long text]\nif Rating <= 2 then show What went wrong?" } } } ``` Then `forms_form_preview` with `{"form": "frm_…", "answers": {"": 1}}` and `forms_form_publish` with `{"form": "frm_…", "expectVersion": 1}`. Tools take the form's id or its slug as `form`. ## Changing a form {#instructions} `forms_form_update` and `PATCH /forms/api/v1/forms/{id}` take a list of instructions that address blocks and rules by id, applied in order, all or none, and only if the form is still at the version you read. The kinds are `addBlock`, `updateBlock`, `moveBlock`, `removeBlock`, `addRule`, `updateRule`, `removeRule`, `reorderRules`, `setTitle`, `setSettings`, `publish` and `close`. The full shapes are in the tool's description and in `contracts/forms-openapi.yaml`; the outline syntax and rule semantics are on [Forms logic, outlines and instructions](/docs/cloud/forms-logic.md). | Option | REST | MCP | What it does | |---|---|---|---| | Version check | `If-Match: ""` or `expectVersion` | `expectVersion` | `409 version_conflict` if the form moved: read it again | | Idempotency | `Idempotency-Key` | `idempotencyKey` | a retry within 24 hours returns the first answer | | Dry run | `dryRun: true` | `dryRun: true` | validates and shows the diff without saving | | Comment | `comment` | `comment` | shown in the history | A bad instruction is `422 invalid_instruction` and names its index and the reason. `forms_form_history` (or `GET …/history`) lists changes with audit ids, and `forms_form_revert` (or `POST …/history` with `auditId`) puts the form back as it was before one. Deleting is for good: `forms_form_delete` needs `confirm` set to the form's id or slug, and `forms_response_delete` needs `confirm: "delete"` (up to 50 responses a call). Both are audited without the content. ## Responses and exports {#responses} - `forms_response_list` and `GET …/responses` return responses oldest first, after a cursor (`after`), with answers keyed by block id. `fields` (MCP) limits the answers to some block ids. - `forms_response_export` returns CSV, at most 1000 rows a call, with the next `after` at the end. `GET …/export` returns up to 50 000 rows in one file. Text that starts with `=`, `+`, `-` or `@` is written with a leading apostrophe. - `GET …/files/{fid}` downloads a file a respondent uploaded (`forms:read`). - `forms_feed_list` and `GET /forms/api/v1/responses` read every form's responses in one list (`forms:read`), newest first; each row carries its form's id, title and slug and a `feedKey`. To follow every form at once, pass `after` (the `latest` of your last call): you get what was submitted since, oldest first, and a new `latest`. - `forms_response_create` and `POST …/responses` submit a response from a backend (`forms:write`), with the same rules as the form's page. See [Submit from a backend](/docs/cloud/forms-responses.md#submit-from-a-backend). ## Events {#events} 1 org webhook event, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `forms.response.created` | A response was submitted to a published Venom Forms form: its id, the form and the time. The answers are included only when the form's "include answers" setting is on (they can be personal data). | `forms.response.created` is sent only for forms with a `webhook` destination. Its data has `form_id`, `form_title`, `response_id`, `version` and `submitted_at`; `answers` and `hidden` are added only when the form's `includeAnswers` setting is on. Each form also has destinations: where its responses are delivered after they are saved. Add them with `forms_form_connect` (`op: "add"`, a `kind` and a `config`), or over REST in `setSettings` (`settings.destinations`, a list of `{id, kind, on, config}`, up to 20). `GET /forms/api/v1/connect` lists what each kind can point at. | Kind | What a response becomes | |---|---| | `globe` | a row in a Notes database in the org vault, questions matched to properties by name (`createDatabase: true` makes one) | | `tasks` | an issue in a Tasks team's Triage, titled from a template | | `webhook` | a `forms.response.created` event to every org webhook endpoint that takes it | | `slack` | a message in a channel, through the org's own Slack app | | `funnel_deal` | a People person made or matched from the contact answers, and a Funnel deal for them in a pipeline | | `support_conversation` | a Venom Support conversation, with the answers as the first message | | `calendar_booking` | a routing step: on submit the respondent books the matching Calendar event type | Delivery is at least once per response and destination. Each is tried at once, then after 1 minute, 5 minutes, 30 minutes and 2 hours, and marked failed after the fifth failure. `forms_delivery_list` and `GET …/deliveries` show the log (state, attempts, last error, what was made); `forms_delivery_retry` and `POST …/deliveries/{did}/retry` send one again. Webhook and Slack deliveries carry answers only when `includeAnswers` is on. See [Send form responses](/docs/cloud/forms-destinations.md). ## REST routes {#rest} The Forms API: 23 operations, generated from `services/nodejs-cloud/contracts/forms-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. **/me** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/forms/api/v1/me` | Who is calling and their permissions (never gated on the add-on). | key or token | **/forms** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/forms/api/v1/forms` | | key or token | | POST | `/forms/api/v1/forms` | | key or token | | GET | `/forms/api/v1/forms/{id}` | | key or token | | PATCH | `/forms/api/v1/forms/{id}` | | key or token | | DELETE | `/forms/api/v1/forms/{id}` | | key or token | | POST | `/forms/api/v1/forms/{id}/preview` | The path these answers take through the form's logic, and what validation says. Nothing is stored. | key or token | | GET | `/forms/api/v1/forms/{id}/responses` | | key or token | | POST | `/forms/api/v1/forms/{id}/responses` | Submit a response from a backend (forms:write): the published version's validation, closed, ended and full forms refused (409 closed, ended, full, not_published), rate limited per credential and per form (429), delivered to every destination. File questions cannot be answered this way. Recorded as submitted by the credential (a response.submit entry in the history). | key or token | | GET | `/forms/api/v1/forms/{id}/summary` | | key or token | | GET | `/forms/api/v1/forms/{id}/history` | | key or token | | POST | `/forms/api/v1/forms/{id}/history` | Put back the form as it was before an audit entry. | key or token | | DELETE | `/forms/api/v1/forms/{id}/responses/{rid}` | Delete one response and its files (forms:write). | key or token | | GET | `/forms/api/v1/forms/{id}/export` | The responses as CSV (up to 50 000; text starting with = + - @ is written with a leading apostrophe). | key or token | | GET | `/forms/api/v1/forms/{id}/files/{fid}` | A file a respondent uploaded, as a download (forms:read). | key or token | | POST | `/forms/api/v1/forms/{id}/logo` | Upload the form's logo: the raw image as the body (PNG, JPEG, WebP or GIF, up to 512 KB). Returns the file id for setSettings theme.logoFileId. | key or token | | GET | `/forms/api/v1/forms/{id}/deliveries` | The delivery log: one row per response and destination, newest first. | key or token | | POST | `/forms/api/v1/forms/{id}/deliveries/{did}/retry` | Send a failed or finished delivery again (forms:write). | key or token | | POST | `/forms/api/v1/forms/{id}/connect/database` | Create a Notes database in the org vault with a property per question; returns the mapping for a Notes destination. | key or token | | POST | `/forms/api/v1/forms/{id}/connect/match` | A mapping of the form's questions to an existing database's properties, matched by name. | key or token | **/responses** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/forms/api/v1/responses` | Every form's responses (forms:read): newest first, paged back with before; or after a feedKey, oldest first, to follow every form at once. latest is the feedKey to pass as after on the next poll. | key or token | **/draft** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/forms/api/v1/draft` | Draft with AI: a prompt in, a markdown outline out, through the organisation's own gear under its daily AI cap. Nothing is stored; POST /forms/api/v1/forms creates from the outline. | key or token | **/connect** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/forms/api/v1/connect` | What a destination can be pointed at: the org vault's databases, Tasks teams with their Triage, whether Slack is connected, how many webhook endpoints take forms.response.created. | key or token | ## MCP tools {#tools} 19 tools: 9 read, 10 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `forms_delivery_list` | List deliveries | read | `forms:read` | | | `forms_delivery_retry` | Retry deliveries | write | `forms:write` | | | `forms_feed_list` | Follow every form's responses | read | `forms:read` | | | `forms_form_close` | Close a form | write (destructive) | `forms:write` | | | `forms_form_connect` | Send responses somewhere | write | `forms:write` | | | `forms_form_create` | Create a form | write | `forms:write` | | | `forms_form_delete` | Delete a form | write (destructive) | `forms:write` | | | `forms_form_get` | Get a form | read | `forms:read` | | | `forms_form_history` | A form's change history | read | `forms:read` | | | `forms_form_list` | List forms | read | `forms:read` | | | `forms_form_preview` | Preview the path through a form | read | `forms:read` | | | `forms_form_publish` | Publish a form | write | `forms:write` | | | `forms_form_revert` | Revert a change | write (destructive) | `forms:write` | | | `forms_form_update` | Change a form | write | `forms:write` | | | `forms_response_create` | Submit a response | write | `forms:write` | | | `forms_response_delete` | Delete responses | write (destructive) | `forms:write` | | | `forms_response_export` | Export responses as CSV | read | `forms:read` | | | `forms_response_list` | Read responses | read | `forms:read` | | | `forms_response_summary` | Summarise responses | read | `forms:read` | | Reads answer as compact markdown, or JSON with `format: "json"`. The tool list is the same for every caller; a read-only credential gets a plain-words refusal when it calls a write tool. ## Related {#related} - [Venom Forms](/docs/cloud/forms.md): the builder. - [Forms logic, outlines and instructions](/docs/cloud/forms-logic.md), [Share a form and take responses](/docs/cloud/forms-sharing.md), [Form responses](/docs/cloud/forms-responses.md) and [Send form responses](/docs/cloud/forms-destinations.md). - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks and events](/docs/developers/webhooks.md) and [MCP](/docs/developers/mcp.md). ================================================================================ # Build on Venom Flags URL: https://cloud.usevenom.dev/docs/developers/flags Description: Create, target, roll out, evaluate and revert feature flags from code or an agent, over the Flags REST API, the SDK endpoints or MCP, and receive every flag change as a signed webhook. Venom Flags holds the organisation's feature flags: projects with environments, and flags whose targeting is set per environment. Everything the app does is also a REST operation under `/flags/api/v1` and an MCP tool. Your own apps read flags through the SDK endpoints under `/flags/sdk` with an environment's keys. Every change is recorded with the caller's name in the flag's history, and any change can be reverted. ## What you can build {#build} - **Release toggles from your deploy pipeline.** Create a temporary flag for each feature (`POST /flags/api/v1/projects/{project}/flags`), turn it on in staging, then roll it out in production with `PATCH /flags/api/v1/projects/{project}/flags/{key}`. - **An agent that runs a rollout.** Connect `venom-flags` and let an agent call `flags_flag_preview`, `flags_flag_rollout` and `flags_flag_revert` if a metric moves the wrong way. - **A change feed into your own audit system.** Create a Flags webhook (`POST /flags/api/v1/webhooks`) and receive each flag, segment, environment, project or webhook change, signed. - **Stale flag cleanup.** Read `GET /flags/api/v1/projects/{project}/stale?env=production` or `flags_flag_list_stale`, open a pull request that removes the code, then archive the flag. - **Code references from CI.** Post where each flag is used (`POST /flags/api/v1/projects/{project}/code-refs`) so the app and `flags_coderef_list` show it. - **Flag values in your app.** Fetch the ruleset (`GET /flags/sdk/ruleset`) or stream changes (`GET /flags/sdk/stream`) with a server SDK key, or ask for client-side values from a browser (`POST /flags/sdk/evaluate`). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/flags`, server name `venom-flags` | | Connect | `claude mcp add --transport http venom-flags https://cloud.usevenom.dev/workspace/mcp/flags` | | MCP tools | 42 (16 read, 26 write) | | OAuth scopes | `flags:read` `flags:write` | | REST twin | none yet | | Flags API | 42 operations | | Webhook events | `flags.flag.created`, `flags.flag.updated`, `flags.flag.deleted` | The older endpoint `/flags/mcp` still serves the same tools, plus the resource `flags://flag/{project}/{key}` (a flag as markdown). `/flags/agents` in the app shows the connect commands with your origin filled in and lists agents' recent changes, each with a Revert button. ## Authentication and scopes {#scopes} Flags uses three permissions: `flags:read`, `flags:write` and `flags:admin`. `flags:admin` covers projects, environments, SDK keys, webhooks, and approving or rejecting approval requests. Who gets which: | Credential | Recorded as | Permissions | |---|---|---| | Personal API key (`vck_…`) | the key's name, `key:` | the member's role: owners and admins have all three, developers read and write, billing and viewer members read | | Team API key | the key's name, `key:` | `flags:read` and `flags:write`; never `flags:admin` | | OAuth app | the app's name, `mcp::` | the member's role, narrowed to the scopes the member granted | - An OAuth token works only on the resource it was issued for. A token for `/workspace/mcp` (or `/workspace/mcp/flags`) carries `flags:read` and `flags:write` but never `flags:admin`, so admin tools refuse it. A token for the `flags` resource (`/flags/mcp`) can carry `flags:admin`, and only such a token works on `/flags/api/v1`. - A request with an API key can send `x-venom-agent: daemon:` or `session:` to record one of the org's daemons or venom sessions as the actor. It grants nothing beyond the key's own rights. - Your app's runtime uses an environment's keys instead: the server SDK key (`vfs_…`), the mobile key (`vfm_…`) and the client-side id (`vfc_…`). They only read flags and send evaluation counts. See [SDK and REST API](/docs/cloud/flags-sdk.md#keys). - If the org has not added Flags, each REST call answers `403 addon_required` and each tool says where to add it. `GET /flags/api/v1/me` always answers, with your permissions and the default project. - Rate limits per credential: 600 requests a minute on `/flags/api/v1`, 240 a minute on `/flags/mcp`. Past the limit you get `429` with `Retry-After`. A refused write is `403` over REST, or a tool error that names the missing permission over MCP. ## Worked example {#example} Create a temporary boolean flag, serve it to 20 % of users in staging, then check what one user gets: ```bash curl -X POST "$VENOM_CLOUD/flags/api/v1/projects/default/flags" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"key": "new-checkout", "kind": "boolean", "temporary": true}' curl -X PATCH "$VENOM_CLOUD/flags/api/v1/projects/default/flags/new-checkout" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -H 'If-Match: "1"' \ -d '{"comment": "20% in staging", "instructions": [ {"kind": "turnFlagOn", "env": "staging"}, {"kind": "updateFallthrough", "env": "staging", "serve": {"rollout": {"variations": [{"variation": 0, "weight": 20000}, {"variation": 1, "weight": 80000}]}}}]}' curl -X POST "$VENOM_CLOUD/flags/api/v1/projects/default/environments/staging/evaluate" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"context": {"kind": "user", "key": "u-123"}, "flags": ["new-checkout"]}' ``` A boolean flag's variations are `[true, false]`, so variation 0 is `true`. Weights are in thousandths of a percent and sum to 100000. The `ETag` of each answer is the flag's version; send it back as `If-Match` on the next write. A `PATCH` in an environment that requires approval answers `202` with a pending request instead of applying. The same over MCP, in one call to `/workspace/mcp/flags`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "flags_batch_run", "arguments": { "steps": [ { "tool": "flags_flag_create", "args": { "key": "new-checkout", "kind": "boolean", "temporary": true } }, { "tool": "flags_flag_toggle", "args": { "key": "$1.key", "env": "staging", "on": true } }, { "tool": "flags_flag_rollout", "args": { "key": "$1.key", "env": "staging", "weights": { "true": 20, "false": 80 }, "comment": "20% in staging" } }, { "tool": "flags_flag_evaluate", "args": { "env": "staging", "context": { "kind": "user", "key": "u-123" }, "flags": ["new-checkout"] } } ] } } } ``` `flags_flag_rollout` takes percentages per variation (by value, name or `#`) and writes the same rollout. `flags_batch_run` runs up to 25 calls in order; a later step can use `$1.key`, `$1.version` or `$1.id` from an earlier one. It stops at the first failure, and steps already run stay applied. ## Writing safely {#safe-change} Every write takes the same options, over REST (headers or body) and MCP (arguments): | Option | REST | MCP | What it does | |---|---|---|---| | Version check | `If-Match: ""` or `expectVersion` | `expectVersion` | refused with `409 version_conflict` if the flag moved on | | Idempotency | `Idempotency-Key` or `idempotencyKey` | `idempotencyKey` | a retry with the same key within 24 hours returns the first answer | | Comment | `comment` | `comment` | shown in the history | | Dry run | `dryRun: true` | `dryRun: true` (on `flags_flag_update`) | shows the diff without saving | A change an agent should make: 1. `flags_flag_get` the flag and note its `version`. 2. `flags_flag_preview` the instructions and `flags_flag_evaluate` two or three real contexts. 3. `flags_flag_update` (or `flags_flag_toggle`, `flags_flag_rollout`) with `expectVersion` and a `comment` saying why. 4. If something goes wrong, `flags_flag_history` shows the change and `flags_flag_revert` undoes it as a new change. `flags_flag_update` and `PATCH …/flags/{key}` take the same instruction list as the app, applied in order, all or none. Rules and clauses are named by id (from `flags_flag_get`), never by position. The full list is in the tool's description and on [SDK and REST API](/docs/cloud/flags-sdk.md#change-a-flag). Agents act alone by default. When an admin turns on **Require approval** for an environment, any change there by a person or an agent becomes an approval request. A member with `flags:admin` approves or rejects it (`flags_approval_decide`, `POST …/approvals/{id}/approve`); the requester or an admin can cancel it. Scheduled changes (`flags_change_schedule`) and approved requests apply without asking again. Keys are secret. `flags_key_rotate` and `POST …/environments/{env}/keys/{which}` (`sdk`, `mobile` or `client`) replace the key at once and return the new one in that answer only. Creating a project returns each environment's keys once. Keep them out of notes, issues and logs. ## Events {#events} 3 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `flags.flag.created` | A feature flag was created in Venom Flags: project, key, name, kind, version, who, and the audit entry. | | `flags.flag.updated` | A feature flag changed (turned on or off, targeting, rollout, variations, archived, or reverted): project, key, version, the environment, whether it is on in each environment, the paths that changed (never their values, which can name users) and who. | | `flags.flag.deleted` | A feature flag was deleted: project, key and who. | Flags has webhooks of its own instead, managed under `/flags/api/v1/webhooks` or with `flags_webhook_create` (`flags:admin`). A webhook gets one `POST` per history entry, for every resource kind or only the `kinds` you list (`flag`, `segment`, `environment`, `project`, `webhook`). - **Event names** are `.`: `flag.create`, `flag.update`, `flag.delete`, `flag.revert`, and the same for `segment`, `environment`, `project` and `webhook`. Rotating a key sends `environment.rotate_sdk_key`, `environment.rotate_mobile_key` or `environment.rotate_client_key`. Archiving and restoring a flag are `flag.update`. - **Body**: `{"event": "flag.update", "tenant": "…", "entry": {…}}`, where `entry` is the history entry: `id`, `seq`, `at`, `project`, `kind`, `key`, `environment`, `action`, `actor`, `comment`, `instructions`, `diff`, `before`, `after`, `version`. - **Headers**: `x-venom-event` (the event name), `x-venom-delivery` (a delivery id), `x-venom-signature: sha256=` (HMAC-SHA256 of the raw body with the webhook's secret). - **Delivery**: 5 second timeout, no redirects followed, any `2xx` counts. A failure is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then dropped. The URL must be `https` (or `http` on `localhost` or `127.0.0.1`) and must not carry credentials. - The signing secret is in the create answer only. To poll instead, `GET /flags/api/v1/projects/{project}/audit?since=` or `flags_flag_history` with `since` return the entries after a sequence number. ## REST routes {#rest} The Flags API: 42 operations, generated from `services/nodejs-cloud/contracts/flags-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. **/me** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/flags/api/v1/me` | Who is calling | key or token | **/projects** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/flags/api/v1/projects` | List projects | key or token | | POST | `/flags/api/v1/projects` | Create a project with production, staging and development (their keys are returned once) | key or token | | GET | `/flags/api/v1/projects/{project}` | Read a project | key or token | | PATCH | `/flags/api/v1/projects/{project}` | Rename or describe a project | key or token | | DELETE | `/flags/api/v1/projects/{project}` | Delete a project and everything in it | key or token | | POST | `/flags/api/v1/projects/{project}/environments` | Create an environment (admin); copyFrom copies targeting | key or token | | PATCH | `/flags/api/v1/projects/{project}/environments/{env}` | Name, colour, requireApproval, confirmChanges, position (admin) | key or token | | DELETE | `/flags/api/v1/projects/{project}/environments/{env}` | Delete an environment (admin; not the last one) | key or token | | POST | `/flags/api/v1/projects/{project}/environments/{env}/keys/{which}` | Rotate a key (admin); the old one stops working at once | key or token | | GET | `/flags/api/v1/projects/{project}/flags` | List flags | key or token | | POST | `/flags/api/v1/projects/{project}/flags` | Create a flag (off in every environment) | key or token | | GET | `/flags/api/v1/projects/{project}/flags/{key}` | Read a flag (ETag is its version) | key or token | | PATCH | `/flags/api/v1/projects/{project}/flags/{key}` | Change a flag with instructions (202 when an environment needs an approval) | key or token | | DELETE | `/flags/api/v1/projects/{project}/flags/{key}` | Delete a flag (revertible from the audit log) | key or token | | POST | `/flags/api/v1/projects/{project}/flags/{key}/preview` | What a change would do: before, after, diff, environments needing approval | key or token | | GET | `/flags/api/v1/projects/{project}/flags/{key}/schedule` | The flag's scheduled changes | key or token | | POST | `/flags/api/v1/projects/{project}/flags/{key}/schedule` | Schedule instructions at executeAt | key or token | | GET | `/flags/api/v1/projects/{project}/flags/{key}/insights` | Hourly evaluation counts per variation and the last evaluation | key or token | | DELETE | `/flags/api/v1/projects/{project}/scheduled/{id}` | Cancel a scheduled change | key or token | | GET | `/flags/api/v1/projects/{project}/environments/{env}/segments` | List segments | key or token | | POST | `/flags/api/v1/projects/{project}/environments/{env}/segments` | Create a segment | key or token | | GET | `/flags/api/v1/projects/{project}/environments/{env}/segments/{key}` | Read a segment | key or token | | PATCH | `/flags/api/v1/projects/{project}/environments/{env}/segments/{key}` | Change a segment with instructions | key or token | | DELETE | `/flags/api/v1/projects/{project}/environments/{env}/segments/{key}` | Delete a segment | key or token | | POST | `/flags/api/v1/projects/{project}/environments/{env}/evaluate` | What a context gets, with reasons (a dry run; never counted) | key or token | | GET | `/flags/api/v1/projects/{project}/audit` | The change log, newest first (since = a sequence number for the change feed) | key or token | | GET | `/flags/api/v1/projects/{project}/audit/{id}` | One change | key or token | | POST | `/flags/api/v1/projects/{project}/audit/{id}/revert` | Restore the resource as it was before this change (409 if it changed since, unless force) | key or token | | GET | `/flags/api/v1/projects/{project}/approvals` | Approval requests | key or token | | POST | `/flags/api/v1/projects/{project}/approvals/{id}/{action}` | Review or apply a request | key or token | | GET | `/flags/api/v1/projects/{project}/stale` | Flags that look ready to remove | key or token | | GET | `/flags/api/v1/projects/{project}/code-refs` | Where flags are used in code | key or token | | POST | `/flags/api/v1/projects/{project}/code-refs` | Replace one repo and branch's references (your CI posts them) | key or token | **/webhooks** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/flags/api/v1/webhooks` | Webhooks (admin) | key or token | | POST | `/flags/api/v1/webhooks` | Create a webhook (admin); its signing secret is returned once | key or token | | PATCH | `/flags/api/v1/webhooks/{id}` | Update a webhook | key or token | | DELETE | `/flags/api/v1/webhooks/{id}` | Delete a webhook | key or token | **/flags** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/flags/sdk/ruleset` | The environment's flags and segments for local evaluation | SDK key | | GET | `/flags/sdk/stream` | Server-sent events: `put` (the ruleset) on connect, `ping` when it changes; ends after about five minutes | SDK key | | POST | `/flags/sdk/evaluate` | Client-side flags' values for one context (browsers and mobile; CORS *) | client id or SDK key | | POST | `/flags/sdk/events` | Batched evaluation summaries (insights) | client id or SDK key | The SDK endpoints, their keys and the TypeScript, Python and Go SDKs are on [SDK and REST API](/docs/cloud/flags-sdk.md). ## MCP tools {#tools} 42 tools: 16 read, 26 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `flags_approval_decide` | Decide an approval request | write | `flags:write` | | | `flags_approval_list` | Approval requests | read | `flags:read` | | | `flags_batch_run` | Run several calls | write | `flags:read` | | | `flags_change_cancel` | Cancel a scheduled change | write | `flags:write` | | | `flags_change_list` | List scheduled changes | read | `flags:read` | | | `flags_change_schedule` | Schedule a change | write | `flags:write` | | | `flags_coderef_list` | Code references | read | `flags:read` | | | `flags_environment_create` | Create an environment | write | `flags:admin` | | | `flags_environment_delete` | Delete an environment | write (destructive) | `flags:admin` | | | `flags_environment_list` | List projects and environments | read | `flags:read` | | | `flags_environment_update` | Update an environment | write | `flags:admin` | | | `flags_flag_archive` | Archive a flag | write | `flags:write` | | | `flags_flag_create` | Create a flag | write | `flags:write` | | | `flags_flag_delete` | Delete a flag | write (destructive) | `flags:write` | | | `flags_flag_evaluate` | Evaluate for a context | read | `flags:read` | | | `flags_flag_get` | Read a flag | read | `flags:read` | | | `flags_flag_history` | History | read | `flags:read` | | | `flags_flag_list` | List flags | read | `flags:read` | | | `flags_flag_list_stale` | Stale flags | read | `flags:read` | | | `flags_flag_preview` | Preview a change | read | `flags:read` | | | `flags_flag_restore` | Restore a flag | write | `flags:write` | | | `flags_flag_revert` | Revert a change | write | `flags:write` | | | `flags_flag_rollout` | Set a percentage rollout | write | `flags:write` | | | `flags_flag_target` | Target contexts individually | write | `flags:write` | | | `flags_flag_toggle` | Turn a flag on or off | write | `flags:write` | | | `flags_flag_update` | Change a flag | write | `flags:write` | | | `flags_insight_get` | Evaluation counts | read | `flags:read` | | | `flags_key_rotate` | Rotate an SDK key | write (destructive) | `flags:admin` | | | `flags_project_create` | Create a project | write | `flags:admin` | | | `flags_project_delete` | Delete a project | write (destructive) | `flags:admin` | | | `flags_project_get` | Read a project | read | `flags:read` | | | `flags_project_list` | List projects | read | `flags:read` | | | `flags_project_update` | Change a project | write | `flags:admin` | | | `flags_segment_create` | Create a segment | write | `flags:write` | | | `flags_segment_delete` | Delete a segment | write (destructive) | `flags:write` | | | `flags_segment_get` | Read a segment | read | `flags:read` | | | `flags_segment_list` | List segments | read | `flags:read` | | | `flags_segment_update` | Change a segment | write | `flags:write` | | | `flags_webhook_create` | Create a webhook | write | `flags:admin` | | | `flags_webhook_delete` | Delete a webhook | write (destructive) | `flags:admin` | | | `flags_webhook_list` | List webhooks | read | `flags:read` | | | `flags_webhook_update` | Change a webhook | write | `flags:admin` | | Every tool takes an optional `project` (default: the org's default project). Reads answer as compact markdown, or JSON with `format: "json"`. The tool list is the same for every caller; a read-only credential is refused in words when it calls a write tool. The Scope column is the OAuth scope; the admin tools also need `flags:admin` from the member's role (see [Authentication and scopes](#scopes)). ## Related {#related} - [Venom Flags](/docs/cloud/flags.md): the app, targeting, stale flags and who can do what. - [SDK and REST API](/docs/cloud/flags-sdk.md): keys, SDKs, the SDK endpoints, code references in CI and errors. - [Build on Venom Experiments](/docs/developers/experiments.md): A/B tests that run through a flag's rollout. - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks and events](/docs/developers/webhooks.md) and [MCP](/docs/developers/mcp.md). ================================================================================ # Build on Venom Experiments URL: https://cloud.usevenom.dev/docs/developers/experiments Description: Define metrics, propose, start, ramp, read and decide A/B tests and guarded rollouts on Venom Flags flags, run product analytics queries and send events, over the Experiments REST API, the event endpoint or MCP. Venom Experiments runs A/B tests and guarded rollouts on [Venom Flags](/docs/developers/flags.md) flags. The flag's rollout assigns units, so there is no second assignment system. Starting, ramping, stopping and deciding are Flags changes made as the caller: they appear in the flag's history, and `flags_flag_revert` undoes them. Everything the app does is a REST operation under `/experiments/api/v1` and an MCP tool. Your apps send events and exposures to `/experiments/sdk/events` with a Flags environment key. ## What you can build {#build} - **Experiments from your planning tool.** Propose a draft on a flag (`POST /experiments/api/v1/experiments`) with a hypothesis, a primary metric and guardrails; the answer has the planned sample and duration. - **An agent that watches results.** Connect `venom-experiments` and have an agent call `exp_experiment_results` each day and `exp_experiment_decide` when the recommendation is clear. - **Guarded rollouts in a release pipeline.** Propose with `kind: "rollout"` and `steps`, start it, and let the sweep ramp the flag while the guardrails hold; pause or resume it with `POST /experiments/api/v1/experiments/{id}/pause` and `/resume`. - **Product analytics in your own dashboard.** Run a trend, funnel or retention query with `POST /experiments/api/v1/query` (or `exp_query_run`), or save it as an insight (`exp_insight_save`) that a Notes page embeds. - **A decision log.** Subscribe an org webhook to `experiments.decided` and copy each decision, with its note and the flag's audit id, into your own records. - **Event tracking from a backend.** Send up to 1000 events and 1000 exposures a request to `POST /experiments/sdk/events` with the environment's server SDK key. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/exp`, server name `venom-experiments` | | Connect | `claude mcp add --transport http venom-experiments https://cloud.usevenom.dev/workspace/mcp/exp` | | MCP tools | 25 (12 read, 13 write) | | OAuth scopes | `experiments:read` `experiments:write` | | REST twin | none yet | | Experiments API | 22 operations | | Webhook events | `experiments.guardrail_breached`, `experiments.decided`, `experiments.started`, `experiments.ramped`, `experiments.stopped` | The older endpoint `/experiments/mcp` still serves the same tools. `/exp/agents` in the app shows the connect commands with your origin filled in. ## Authentication and scopes {#scopes} An experiment is a way of changing a flag, so Experiments checks Flags' permissions: `flags:read` to read and `flags:write` to change. They come from the same places as in Flags: - A **personal API key** acts with its member's role: owners, admins and developers read and write; billing and viewer members read. - A **team key** reads and writes. - An **OAuth app** needs `experiments:read` (which stands for `flags:read`) and `experiments:write` (which stands for `flags:write`), within what the member's role allows. A token for `/workspace/mcp` or `/workspace/mcp/exp` works on those endpoints; only a token for the `experiments` resource (`/experiments/mcp`) works on `/experiments/api/v1`. - The event endpoint `/experiments/sdk/events` takes an environment's server SDK key (`vfs_…`), mobile key (`vfm_…`) or client-side id (`vfc_…`), the same keys as [Flags' SDK endpoints](/docs/cloud/flags-sdk.md#keys). - The org needs the Experiments add-on; otherwise each REST call answers `403 addon_required` and each tool says where to add it. - Rate limits per credential: the REST API shares Flags' 600 requests a minute; `/experiments/mcp` allows 240 a minute. Past the limit you get `429` with `Retry-After`. In an environment that requires approval, a start, ramp, stop or decide becomes a Flags approval request instead of applying, and the answer says so (`flagChange.pendingApproval`). ## Worked example {#example} Define a conversion metric, propose an experiment on the `new-checkout` flag, start it, then read its results: ```bash BASE="$VENOM_CLOUD/experiments/api/v1" H="Authorization: Bearer $VENOM_API_KEY" curl -X POST "$BASE/metrics" -H "$H" -H 'Content-Type: application/json' \ -d '{"environment": "production", "key": "purchase", "type": "conversion", "event": "checkout_completed"}' curl -X POST "$BASE/experiments" -H "$H" -H 'Content-Type: application/json' -H 'Idempotency-Key: exp-checkout-1' \ -d '{"flag": "new-checkout", "primary": "purchase", "hypothesis": "A one-page checkout converts better.", "guardrails": [{"metric": "checkout_errors", "tolerated": 0.02}]}' curl -X POST "$BASE/experiments//start" -H "$H" -H 'Content-Type: application/json' -H 'If-Match: "1"' \ -d '{"turnOn": true, "comment": "50/50 in production"}' curl "$BASE/experiments//results" -H "$H" ``` The guardrail metric must exist too. Start, ramp, pause, resume, stop and decide answer `{experiment, flagChange: {auditId, diff, pendingApproval, dryRun}, warnings}`; `flagChange.auditId` is the Flags history entry to revert. Each answer's `ETag` is the experiment's version. The same proposal over MCP, from any client connected to `/workspace/mcp/exp`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "exp_experiment_propose", "arguments": { "flag": "new-checkout", "primary": "purchase", "hypothesis": "A one-page checkout converts better.", "guardrails": [{ "metric": "checkout_errors", "tolerated": 0.02 }], "idempotencyKey": "exp-checkout-1" } } } ``` Then `exp_experiment_start` with `{"id": "", "turnOn": true, "expectVersion": 1}` and `exp_experiment_results` with `{"id": ""}`. ## Running an experiment {#run} A typical run for an agent: 1. `exp_metric_list`, then `exp_metric_create` for what is missing (`count`, `sum`, `conversion`, `ratio` or `retention` over tracked events; `direction: "down"` when less is better). 2. `exp_experiment_propose` with the flag, the primary metric, a hypothesis and guardrails. `exp_plan_get` (or `GET /experiments/api/v1/plan?primary=…`) estimates the sample alone, saving nothing. 3. `exp_experiment_start`. It is refused when the flag is off in the environment unless `turnOn` is true. 4. `exp_experiment_results` each day. `recommendation.action` is `ship`, `rollback`, `keep_running`, `inconclusive` or `investigate`. `investigate` means a sample ratio mismatch: do not act on the numbers. 5. `exp_experiment_decide` with `decision` (`ship` with a `variation` index, `rollback` or `iterate`) and a `reason`. It applies the Flags change, writes a decision note into Notes and sends `experiments.decided`. Writes take `expectVersion` (or `If-Match`), `idempotencyKey` (or `Idempotency-Key`; a retry within 24 hours returns the first answer), `comment` (shown in the flag's history) and `dryRun`. Shares are in thousandths of a percent (50000 = 50 %), between 1000 and 99000. Ramping restarts the analysis, so ramp early and rarely. A metric an experiment uses can only be renamed. A guarded rollout (`kind: "rollout"`) needs at least one guardrail. Its default ladder is 1 %, 5 %, 25 %, 50 %, then 100 %, a day each. The sweep advances it, promotes it after the last step, or rolls it back and files a Tasks issue when a guardrail breaks. `exp_experiment_rollout` (`action: "pause"` or `"resume"`) holds it; a breach still rolls a paused rollout back. ## Sending events {#ingest} `POST /experiments/sdk/events` takes `{"events": [...], "exposures": [...]}`: up to 1000 of each, 512 KB. An event is `{event, unit: {kind, key}, value?, props?, ts?}`; `props` is at most 2 KB of JSON. Invalid entries are dropped and counted in the `202` answer. Past the org's daily cap it answers `429` with `Retry-After`. See [Sending events](/docs/cloud/experiments-events.md) for the TypeScript SDK's `track()` and retention. ## Events {#events} 5 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `experiments.guardrail_breached` | A guardrail metric of a running experiment is worse than its tolerated regression (once per experiment and metric). | | `experiments.decided` | An experiment was decided: a variation shipped, a rollback or an iteration, by a person, an agent or the automatic guardrail rollback. | | `experiments.started` | An experiment started serving its treatments (by a person, an agent, or an approved request): the experiment, flag, environment, the treatments' share and who started it. | | `experiments.ramped` | A running experiment's treatment share changed (by hand, or a guarded rollout's next step): the share before and after, and who. | | `experiments.stopped` | A running experiment was stopped and control is served to everyone: the experiment, flag, environment and who stopped it. | The data of both events has the experiment's `experiment` id, `name`, `flag`, `project`, `environment` and `url`. `experiments.decided` adds `decision`, `variation`, `reason`, `note` (the decision note's path) and `auditId` (the flag's history entry); an automatic rollback adds `automatic: true`. `experiments.guardrail_breached` adds `metric`, `arm`, `harm`, `tolerated`, `p` and `autoRollback`, and is sent once per experiment and metric. Experiments has no webhooks of its own. The flag changes it makes also reach [Flags webhooks](/docs/developers/flags.md#events) as `flag.update`. ## REST routes {#rest} The Experiments API: 22 operations, generated from `services/nodejs-cloud/contracts/experiments-openapi.yaml`. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime. **/experiments** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/experiments/sdk/events` | Send events and exposures | SDK key or client id | | GET | `/experiments/api/v1/experiments` | List experiments | key or token | | POST | `/experiments/api/v1/experiments` | Propose an experiment (a draft; nothing is served yet) | key or token | | GET | `/experiments/api/v1/experiments/{id}` | Get an experiment | key or token | | PATCH | `/experiments/api/v1/experiments/{id}` | Edit a draft | key or token | | GET | `/experiments/api/v1/experiments/{id}/results` | Results from the daily rollups, cached until they change | key or token | | GET | `/experiments/api/v1/experiments/{id}/timeline` | The primary metric's cumulative lift by day, for a chart | key or token | | POST | `/experiments/api/v1/experiments/{id}/{action}` | Start, ramp, stop or decide an experiment (each is a Flags change as the caller) | key or token | **/events** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/experiments/api/v1/events` | The events explorer - event names with 14 days of volume, and a sample of recent events | key or token | **/plan** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/experiments/api/v1/plan` | Plan an experiment - the sample it needs and how long recent traffic takes to deliver it (nothing is saved) | key or token | **/query** | Method | Path | Summary | Auth | |---|---|---|---| | POST | `/experiments/api/v1/query` | Run a trend, funnel or retention query (read-only, time-limited; nothing is saved) | key or token | **/insights** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/experiments/api/v1/insights` | List saved insights of an environment | key or token | | POST | `/experiments/api/v1/insights` | Save a query as an insight | key or token | | GET | `/experiments/api/v1/insights/{id}` | One insight | key or token | | PATCH | `/experiments/api/v1/insights/{id}` | Rename an insight or change its query (If-Match with its version) | key or token | | DELETE | `/experiments/api/v1/insights/{id}` | Delete an insight (Notes pages that embed it show "Insight unavailable") | key or token | | GET | `/experiments/api/v1/insights/{id}/result` | Run a saved insight now - what a Notes page embedding it shows | key or token | **/metrics** | Method | Path | Summary | Auth | |---|---|---|---| | GET | `/experiments/api/v1/metrics` | List metrics of an environment | key or token | | POST | `/experiments/api/v1/metrics` | Create a metric | key or token | | GET | `/experiments/api/v1/metrics/{key}` | Get a metric | key or token | | PATCH | `/experiments/api/v1/metrics/{key}` | Update a metric (not what it measures while an experiment uses it) | key or token | | DELETE | `/experiments/api/v1/metrics/{key}` | Delete a metric no experiment uses | key or token | ## MCP tools {#tools} 25 tools: 12 read, 13 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `exp_event_list` | List events | read | `experiments:read` | | | `exp_experiment_decide` | Decide an experiment | write | `experiments:write` | | | `exp_experiment_get` | Get an experiment | read | `experiments:read` | | | `exp_experiment_list` | List experiments | read | `experiments:read` | | | `exp_experiment_propose` | Propose an experiment | write | `experiments:write` | | | `exp_experiment_ramp` | Ramp an experiment | write | `experiments:write` | | | `exp_experiment_results` | Experiment results | read | `experiments:read` | | | `exp_experiment_rollout` | Pause or resume a rollout | write | `experiments:write` | | | `exp_experiment_start` | Start an experiment | write | `experiments:write` | | | `exp_experiment_stop` | Stop an experiment | write | `experiments:write` | | | `exp_experiment_timeline` | Experiment lift over time | read | `experiments:read` | | | `exp_experiment_update` | Change a draft experiment | write | `experiments:write` | | | `exp_insight_delete` | Delete an insight | write (destructive) | `experiments:write` | | | `exp_insight_get` | Read an insight | read | `experiments:read` | | | `exp_insight_list` | List insights | read | `experiments:read` | | | `exp_insight_result` | Run an insight | read | `experiments:read` | | | `exp_insight_save` | Save an insight | write | `experiments:write` | | | `exp_insight_update` | Change an insight | write | `experiments:write` | | | `exp_metric_create` | Create a metric | write | `experiments:write` | | | `exp_metric_delete` | Delete a metric | write (destructive) | `experiments:write` | | | `exp_metric_get` | Read a metric | read | `experiments:read` | | | `exp_metric_list` | List metrics | read | `experiments:read` | | | `exp_metric_update` | Change a metric | write | `experiments:write` | | | `exp_plan_get` | Plan a sample size | read | `experiments:read` | | | `exp_query_run` | Run a trend, funnel or retention query | read | `experiments:read` | | Each tool takes `format: "json"` for a structured answer instead of compact markdown. `project` defaults to the org's default Flags project and `environment` to `production`. The tool list is the same for every caller; a read-only credential is refused in words when it calls a write tool. ## Related {#related} - [Venom Experiments](/docs/cloud/experiments.md): metrics, the analysis, sample ratio mismatch and guarded rollouts. - [Sending events](/docs/cloud/experiments-events.md) and [Insights and dashboards](/docs/cloud/experiments-insights.md). - [Build on Venom Flags](/docs/developers/flags.md): the flags experiments run on, and how to revert a change. - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks and events](/docs/developers/webhooks.md) and [MCP](/docs/developers/mcp.md). ================================================================================ # Build on Org and teams URL: https://cloud.usevenom.dev/docs/developers/org Description: Read and manage the organisation's teams, subteams and team members from code or an agent, over REST or MCP, with the same rules as Settings, Teams. An org has one tree of teams and subteams, shared by Tasks, Notes, People, Calendar and the other products. Each team has members (people `user:` and agents `agent:`) with a team role, `admin` or `member`. Everything **Settings → Teams** does is also an `org_team_*` MCP tool and a REST route under `/api/v1/org/teams`. Each tool calls the same functions as the console, so the permission checks, the Tasks and Notes mirrors and the audit rows are the same, with your credential as the actor. The model itself (subteams, membership that flows down, private teams, teams synced from your identity provider) is described in [Teams, subteams and roles](/docs/cloud/teams.md). This page covers calling it. ## What you can build {#build} - **Teams from your HR system or org chart.** Create a team for each department (`POST /api/v1/org/teams`), nest subteams with `parentId`, and move them when the org chart changes (`POST /api/v1/org/teams/{teamId}/move`). - **Onboarding and offboarding.** Add a new hire to their team (`org_team_member_add`) and take a leaver out of every team (`org_team_member_remove`). Members of a team are members of its subteams too, so one add is usually enough. - **Team pickers in your own app.** Read the tree you are allowed to see (`GET /api/v1/org/teams`) and use a team's `id` when you create work in Tasks, Notes or Calendar. - **An access review.** List each team's members with the ones they inherit from teams above (`GET /api/v1/org/teams/{teamId}/members?inherited=true`) and compare them with your directory. - **A service agent that runs its own team.** Bind a team key to a service agent, make that agent a team admin, and let it manage that team and its subteams without a person's key. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/org`, server name `venom-org` | | Connect | `claude mcp add --transport http venom-org https://cloud.usevenom.dev/workspace/mcp/org` | | MCP tools | 10 (3 read, 7 write) | | OAuth scopes | `org:read` `org:write` | | REST twin | 10 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `org.team.created`, `org.team.updated`, `org.team.archived`, `org.team.member_added`, `org.team.member_removed` | ## Authentication and scopes {#scopes} Who you act as depends on the credential: - A **personal API key** acts as its member (`user:`) with their org role. Org owners and admins manage every team. Anyone else manages only the teams they are an admin of, and their subteams. Everyone reads the teams that are not private, plus the private teams they are in. A read-only personal key only reads. If the member has left the org, the key is refused. - A **team key bound to a service agent** acts as that agent (`agent:`). It has no org role, so it manages only the teams the agent is an admin of. Its reads follow the same visibility rules. - A **team key with no agent bound** has no member at all. It reads the teams that are not private and is refused every change. - An **OAuth app** acts as the member who connected it. It needs `org:read` to use the tools at all and `org:write` to change anything, on top of that member's rights. Some refusals come from the team, not the credential: a team that syncs from your identity provider refuses member changes, a team keeps at least one admin once it has one, and a team cannot move under itself or one of its subteams. A private team you may not see answers "No such team", the same as a missing one. Over REST a refusal is `403`, a missing team `404`, a bad field `400`. Over MCP the tool returns an error with the reason in words. See [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ## Worked example {#example} Create a Platform subteam under Engineering and add a new hire to it as a member: ```bash # Find Engineering's id in the tree curl "$VENOM_CLOUD/api/v1/org/teams" -H "Authorization: Bearer $VENOM_API_KEY" # Make the subteam (you become its first admin) curl -X POST "$VENOM_CLOUD/api/v1/org/teams" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"name": "Platform", "key": "PLAT", "parentId": "", "description": "Build, deploy and runtime"}' # Add a person to it curl -X POST "$VENOM_CLOUD/api/v1/org/teams//members" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"member": "user:", "role": "member"}' ``` A person's id is their `clerk_user_id` from `admin_member_list`; an agent is `agent:`. The same two changes over MCP, from any client connected to `/workspace/mcp/org`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "org_team_create", "arguments": { "name": "Platform", "key": "PLAT", "parentId": "", "description": "Build, deploy and runtime" } } } ``` ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "org_team_member_add", "arguments": { "teamId": "", "member": "user:", "role": "member" } } } ``` Tools answer in compact markdown by default. Pass `"format": "json"` for the structured answer (the team, or the team's direct members after a member change). Adding someone who is already in the team changes their role instead. ## Events {#events} 5 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `org.team.created` | A team was created in the organisation (shared by Tasks, Chat, Notes and People): id, key, name, parent, whether it is private, and who. | | `org.team.updated` | A team's name, key, parent, privacy or description changed: the team as it is now, and who. | | `org.team.archived` | A team was archived (or restored: `archived` false), and who did it. | | `org.team.member_added` | A person or agent joined a team: the team, the member's id, their role in it, and who added them. | | `org.team.member_removed` | A person or agent left a team: the team, the member's id and who removed them. | Every team change is in the org's audit log with the credential as actor: `org.team.created`, `org.team.updated`, `org.team.moved`, `org.team.archived`, `org.team.unarchived`, `org.team.member_added`, `org.team.role_changed`, `org.team.member_removed`, `org.team.left` and `org.team.synced` (a SCIM group sync). A caller that may read the audit log can follow them with `admin_audit_list` and the action prefix `org.team` (`GET /api/v1/admin/audit?action=org.team`); see [Build on Admin and the mesh](/docs/developers/admin.md). ## REST routes {#rest} The REST twin: 10 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/org/teams` | The organisation's teams as a tree | `org_team_list` | | POST | `/api/v1/org/teams` | Create a team, or a subteam with parentId | `org_team_create` | | GET | `/api/v1/org/teams/{teamId}` | A team with its place in the tree, subteams and members | `org_team_get` | | PATCH | `/api/v1/org/teams/{teamId}` | Rename a team, or change its description, key or private flag | `org_team_update` | | POST | `/api/v1/org/teams/{teamId}/move` | Put a team under another team, or at the top with parentId null | `org_team_move` | | POST | `/api/v1/org/teams/{teamId}/archive` | Archive a team, or bring it back with archived false | `org_team_archive` | | GET | `/api/v1/org/teams/{teamId}/members` | A team's members, with those inherited from the teams above | `org_team_members` | | POST | `/api/v1/org/teams/{teamId}/members` | Add a person (user:) or an agent (agent:) to a team | `org_team_member_add` | | PATCH | `/api/v1/org/teams/{teamId}/members/{member}` | Make a team member an admin or a member | `org_team_member_role` | | DELETE | `/api/v1/org/teams/{teamId}/members/{member}` | Take a person or agent out of a team | `org_team_member_remove` | ## MCP tools {#tools} 10 tools: 3 read, 7 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `org_team_archive` | Archive a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/archive` | | `org_team_create` | Create a team | write | `org:write` | `POST /api/v1/org/teams` | | `org_team_get` | Read a team | read | `org:read` | `GET /api/v1/org/teams/{teamId}` | | `org_team_list` | List the organisation's teams | read | `org:read` | `GET /api/v1/org/teams` | | `org_team_member_add` | Add a member to a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/members` | | `org_team_member_remove` | Remove a member from a team | write (destructive) | `org:write` | `DELETE /api/v1/org/teams/{teamId}/members/{member}` | | `org_team_member_role` | Change a member's team role | write | `org:write` | `PATCH /api/v1/org/teams/{teamId}/members/{member}` | | `org_team_members` | List a team's members | read | `org:read` | `GET /api/v1/org/teams/{teamId}/members` | | `org_team_move` | Move a team | write | `org:write` | `POST /api/v1/org/teams/{teamId}/move` | | `org_team_update` | Rename or change a team | write | `org:write` | `PATCH /api/v1/org/teams/{teamId}` | Linking a SCIM group to a team is an admin tool, not an `org_team_*` one: `admin_sso_group_list` and `admin_sso_group_team_set`, owners only ([Teams from your identity provider](/docs/cloud/teams.md)). ## Related {#related} - [Teams, subteams and roles](/docs/cloud/teams.md): the model, org roles per product, private and synced teams. - [Build on Admin and the mesh](/docs/developers/admin.md): members, invitations and the rest of the org's settings. - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Computers URL: https://cloud.usevenom.dev/docs/developers/computers Description: Give agents their own persistent browsers on your daemons from code or an agent. Create, start and stop computers, read what they did, ask a person to take over and manage a shared computer's agents over MCP. A computer is one agent's browser profile (cookies, logins, local storage and a files directory) on one of your organisation's daemons. The cloud starts, stops and watches computers; the agent and its browser run on the daemon. See [What a computer is](/docs/computers/overview.md) for placement, hibernation and control. ## What you can build {#build} - **An agent that brings its own browser.** On first run the agent calls `computers_seat_create` for its own computer, then `computers_seat_start` before each job and `computers_seat_stop` when it is done. Logins survive the stop. - **A shared inbox browser.** Create a `shared` computer, sign in to WhatsApp Web or a supplier portal once, and add the agents that need it with `computers_member_add`. - **A hand-off for logins and 2FA.** When the agent meets a login, a 2FA prompt or a CAPTCHA it calls `computers_takeover_request`; the computer shows Needs you and its owner is told. - **An audit view.** Read `computers_activity_list` (navigations by host, clicks, how much was typed but never what, downloads, takeovers) into your own log store. Activity is kept 30 days. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/computers`, server name `venom-computers` | | Connect | `claude mcp add --transport http venom-computers https://cloud.usevenom.dev/workspace/mcp/computers` | | MCP tools | 36 (15 read, 21 write) | | OAuth scopes | `computers:read` `computers:write` | | REST twin | none yet | | Webhook events | none yet | ## Authentication and scopes {#scopes} Computers needs the `computers` add-on (the Team plan and up). Without it every call answers `403 addon_required` with an `upgrade_url`. - A **personal API key or an OAuth grant** acts as the member, with their org role's rights. OAuth apps need `computers:read` for the read tools and `computers:write` for the rest. - A **team key bound to a service agent**, or a key naming an agent with `x-venom-agent`, acts as that agent. It sees and uses its own computer and the shared computers it belongs to, creates its own computer only, and cannot archive a computer or change members. - A **team key with no agent** only reads. Archiving a computer and changing a shared computer's agents need an org admin or the person who created it. ## Worked example {#example} An agent creates and starts its own computer, then asks for help at a login. `$VENOM_TEAM_KEY` is a team key (not marked "This key is mine"), and `x-venom-agent` names the agent it acts as ([Naming agents on a shared key](/docs/developers/auth.md#agent-header)). A personal key would act as its member instead. ```bash curl -X POST "$VENOM_CLOUD/workspace/mcp/computers" \ -H "Authorization: Bearer $VENOM_TEAM_KEY" -H 'x-venom-agent: invoice-bot' \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "computers_seat_create", "arguments": {"name": "Invoice bot", "format": "json"}}}' ``` Then, with the computer's `id` from that answer: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "computers_seat_start", "arguments": { "seat_id": "" } } } { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "computers_takeover_request", "arguments": { "seat_id": "", "reason": "Sign in to the supplier portal; it asks for a 2FA code." } } } ``` `computers_seat_start` answers the state the computer has: `active`, `starting` while the daemon has not answered, or `queued` with how many are ahead when the daemon is full. Read it again with `computers_seat_get` until it is `active`. After a takeover, wait until it is `active` again, then read the page and carry on. Never put passwords or codes in `reason`. Errors worth handling: `409 no_capacity` (no daemon has room for another computer), `409 seat_exists` (the agent already has one: list it instead), `daemon_offline` and `seat_archived`. ## Events {#events} This product sends no org webhook events yet. Follow its changes with `workspace_change_list` where it has a change feed, or poll its list routes. To follow a computer, poll `computers_seat_get` for its state or `computers_activity_list` with the previous page's `before` cursor. ## REST routes {#rest} No REST routes yet: use the MCP tools. The console's own API under `/api/workspace/computers` mirrors the tools for the signed-in browser session; it does not take API keys. Its routes are listed in [Computers for agents](/docs/computers/agents.md#rest). ## MCP tools {#tools} 36 tools: 15 read, 21 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `computers_activity_list` | List a computer's activity | read | `computers:read` | | | `computers_agent_get` | Read whether an agent uses a computer | read | `computers:read` | | | `computers_agent_set` | Give an agent a computer | write | `computers:write` | | | `computers_approval_decide` | Answer an approval or a takeover | write | `computers:write` | | | `computers_approval_list` | List what agents wait on a person for | read | `computers:read` | | | `computers_credential_create` | Save a login or card | write | `computers:write` | | | `computers_credential_delete` | Revoke a saved login | write (destructive) | `computers:write` | | | `computers_credential_list` | List saved logins | read | `computers:read` | | | `computers_daemon_disable` | Disable Computers on a daemon | write | `computers:write` | | | `computers_daemon_enable` | Enable Computers on a daemon | write | `computers:write` | | | `computers_daemon_list` | List daemons and their Computers setup | read | `computers:read` | | | `computers_member_add` | Add an agent to a shared computer | write | `computers:write` | | | `computers_member_list` | List a shared computer's agents | read | `computers:read` | | | `computers_member_remove` | Remove an agent from a shared computer | write (destructive) | `computers:write` | | | `computers_routine_create` | Create a routine | write | `computers:write` | | | `computers_routine_delete` | Delete a routine | write (destructive) | `computers:write` | | | `computers_routine_get` | Read a routine | read | `computers:read` | | | `computers_routine_list` | List routines | read | `computers:read` | | | `computers_routine_rotate_secret` | Rotate a routine's secret | write | `computers:write` | | | `computers_routine_run_get` | Read a routine run | read | `computers:read` | | | `computers_routine_run_list` | List routine runs | read | `computers:read` | | | `computers_routine_run_now` | Run a routine now | write | `computers:write` | | | `computers_routine_update` | Change a routine | write | `computers:write` | | | `computers_run_list` | List agents' runs on computers | read | `computers:read` | | | `computers_run_stop` | Stop an agent's run | write (destructive) | `computers:write` | | | `computers_seat_create` | Create a computer | write | `computers:write` | | | `computers_seat_delete` | Archive a computer | write (destructive) | `computers:write` | | | `computers_seat_get` | Read a computer | read | `computers:read` | | | `computers_seat_list` | List computers | read | `computers:read` | | | `computers_seat_start` | Start a computer | write | `computers:write` | | | `computers_seat_stop` | Stop a computer | write | `computers:write` | | | `computers_seat_update` | Rename or change a computer | write | `computers:write` | | | `computers_tab_list` | List a shared computer's shared tabs | read | `computers:read` | | | `computers_tab_share` | Mark a tab as shared | write | `computers:write` | | | `computers_takeover_request` | Ask a person to take over | write | `computers:write` | | | `computers_thumbnail_get` | See a computer's screen | read | `computers:read` | | Every tool takes `format: "json"` for structured content and refuses arguments it does not list. ## Related {#related} - [What a computer is](/docs/computers/overview.md) and [Computers for agents](/docs/computers/agents.md). - [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Agents URL: https://cloud.usevenom.dev/docs/developers/agents Description: Start and drive chats with coding agents on your daemons' projects and with agents on your computers, from code or another agent, over MCP or REST. A chat is one conversation with one agent that runs on your organisation's own machines: a coding agent in a project directory a daemon offers, or an agent on one of your computers. The cloud relays messages and events; the repository and the conversation stay on the daemon. See [Venom Agents](/docs/agents.md). ## What you can build {#build} - **A script that hands work to a coding agent.** List a daemon's projects with `agents_project_list` (or make one with `agents_workspace_create`, cloned from a repository), start a chat with `agents_chat_create` and a `prompt`, then read `agents_transcript_get` until the run is done. - **An approvals bot.** Read the transcript or the console's event stream for `approval_request` events and answer them with `agents_approval_decide` (`allow-once`, `allow-session`, `allow-project` or `deny`). - **A review step.** After a run, read the files each turn changed with `agents_change_get` (`turn`: a checkpoint's `entryId`). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/agents`, server name `venom-agents` | | Connect | `claude mcp add --transport http venom-agents https://cloud.usevenom.dev/workspace/mcp/agents` | | MCP tools | 48 (21 read, 27 write) | | OAuth scopes | `agents:read` `agents:write` | | REST twin | 48 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | none yet | ## Authentication and scopes {#scopes} Agents needs the `agents` add-on (the Team plan and up). Without it every call answers `403 addon_required`. - A **personal API key or an OAuth grant** acts as the member. OAuth apps need `agents:read` for the read tools and `agents:write` for the rest; a computer chat also needs the member's right to use that computer. - **Any other key** has no access: a chat belongs to a person. Only the member who started a chat sends to it. Org owners and admins read every member's chats (`all: true`). ## Worked example {#example} ```bash curl -X POST "$VENOM_CLOUD/workspace/mcp/agents" \ -H "Authorization: Bearer $VENOM_PERSONAL_KEY" \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "agents_chat_create", "arguments": {"daemon_id": "", "project": "/home/me/src/app", "prompt": "Fix the failing tests", "format": "json"}}}' ``` Then, with the chat's `id`: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "agents_transcript_get", "arguments": { "chat_id": "" } } } ``` While a run is active a new `prompt` answers `409 busy`: send it with `delivery: "steer"` or `"follow_up"` instead. Errors worth handling: `501 projects_unavailable` (the daemon is too old to list projects), `503 session_daemon_unavailable` (the chat's daemon is offline), `409 chat_archived`, `409 member_gone`. ## Events {#events} This product sends no org webhook events yet. Follow its changes with `workspace_change_list` where it has a change feed, or poll its list routes. The live stream (`GET /api/workspace/agents/chats/{id}/events`) is for the signed-in browser; an agent reads the transcript. ## REST routes {#rest} The REST twin: 48 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/agents/chats` | Your chats with agents (admins: all for every member's) | `agents_chat_list` | | POST | `/api/v1/agents/chats` | Start a chat: a coding agent in a daemon's project (or a new scratch folder), or an agent on a computer, with an optional first prompt | `agents_chat_create` | | GET | `/api/v1/agents/chats/{chat_id}` | One chat | `agents_chat_get` | | PATCH | `/api/v1/agents/chats/{chat_id}` | Rename a chat, change its permission mode or shift its gear; a quick chat's servers | `agents_chat_update` | | DELETE | `/api/v1/agents/chats/{chat_id}` | Archive a chat; its session is closed | `agents_chat_archive` | | POST | `/api/v1/agents/chats/{chat_id}/messages` | Send a message: a prompt, or steer or follow up a running turn | `agents_chat_send` | | POST | `/api/v1/agents/attachments` | Upload a file or picture for your next quick-chat message (base64) | `agents_attachment_upload` | | DELETE | `/api/v1/agents/attachments/{file_id}` | Remove a file you uploaded and have not sent | `agents_attachment_delete` | | GET | `/api/v1/agents/chats/{chat_id}/attachments` | A chat's files and pictures | `agents_attachment_list` | | POST | `/api/v1/agents/chats/{chat_id}/abort` | Stop the running turn | `agents_chat_stop` | | POST | `/api/v1/agents/chats/{chat_id}/approvals/{approval_id}` | Answer an approval the agent asked for | `agents_approval_decide` | | POST | `/api/v1/agents/chats/{chat_id}/questions/{question_id}` | Answer a question the agent asked | `agents_question_respond` | | GET | `/api/v1/agents/chats/{chat_id}/transcript` | The conversation so far | `agents_transcript_get` | | GET | `/api/v1/agents/chats/{chat_id}/changes` | The turns that changed files, or one turn's file changes (turn) | `agents_change_get` | | GET | `/api/v1/agents/gears` | The gears a chat can run in: the org's, then the daemon's own or venom's built-ins | `agents_gear_list` | | GET | `/api/v1/agents/projects` | The project directories a daemon offers | `agents_project_list` | | GET | `/api/v1/agents/workspaces` | The workspaces on a daemon (durable and scratch) | `agents_workspace_list` | | POST | `/api/v1/agents/workspaces` | Make a workspace on a daemon: empty, cloned from an https URL, or scratch | `agents_workspace_create` | | GET | `/api/v1/agents/servers` | The MCP servers a quick chat can use, and your catalog connections | `agents_server_list` | | GET | `/api/v1/agents/skills` | The organisation's skills a quick chat can use | `agents_skill_list` | | POST | `/api/v1/agents/connections` | Connect a catalog MCP server for quick chats (an OAuth server answers the sign-in link) | `agents_connection_create` | | DELETE | `/api/v1/agents/connections/{server}` | Disconnect a catalog MCP server | `agents_connection_delete` | | GET | `/api/v1/agents/bots` | Your bots: named agents with an avatar and standing instructions | `agents_bot_list` | | POST | `/api/v1/agents/bots` | Make a bot, or a ready-made one with its routines (template) | `agents_bot_create` | | GET | `/api/v1/agents/bots/{bot_id}` | One of your bots, with its instructions | `agents_bot_get` | | PATCH | `/api/v1/agents/bots/{bot_id}` | Change a bot | `agents_bot_update` | | DELETE | `/api/v1/agents/bots/{bot_id}` | Delete a bot and its routines (its chats stay) | `agents_bot_delete` | | GET | `/api/v1/agents/bots/{bot_id}/memory` | A bot's memory note | `agents_bot_memory_get` | | PUT | `/api/v1/agents/bots/{bot_id}/memory` | Rewrite a bot's memory note | `agents_bot_memory_update` | | GET | `/api/v1/agents/bots/{bot_id}/outreach` | How a bot reaches out: mode, channels, caps and today's counts, pacing, quiet hours, who it may contact, what waits for you, its ledger | `agents_bot_outreach_get` | | PATCH | `/api/v1/agents/bots/{bot_id}/outreach` | Change how a bot reaches out (owner only) | `agents_bot_outreach_update` | | POST | `/api/v1/agents/bots/{bot_id}/outreach/decide` | Approve or decline what a bot's runs left waiting, all or some | `agents_bot_outreach_decide` | | POST | `/api/v1/agents/bots/{bot_id}/outreach/release` | Let a bot write again to someone who replied to it | `agents_bot_outreach_release` | | GET | `/api/v1/agents/bots/summary` | Your bots at a glance: next and last run, needs-you count, spend, working now | `agents_bot_summary_list` | | GET | `/api/v1/agents/bots/brief` | What your bots did since you last looked | `agents_bot_brief_get` | | DELETE | `/api/v1/agents/bots/brief` | Dismiss the brief | `agents_bot_brief_dismiss` | | GET | `/api/v1/agents/routines` | Your bots' routines | `agents_bot_routine_list` | | POST | `/api/v1/agents/routines` | Make a bot run by itself on a schedule, an email, a webhook or events in the workspace | `agents_bot_routine_create` | | GET | `/api/v1/agents/routines/{routine_id}` | One of your bots' routines | `agents_bot_routine_get` | | PATCH | `/api/v1/agents/routines/{routine_id}` | Change a bot's routine | `agents_bot_routine_update` | | DELETE | `/api/v1/agents/routines/{routine_id}` | Delete a bot's routine | `agents_bot_routine_delete` | | POST | `/api/v1/agents/routines/{routine_id}/run` | Run a bot's routine now | `agents_bot_routine_run` | | POST | `/api/v1/agents/routines/{routine_id}/secret` | A new secret for a bot's webhook or email routine | `agents_bot_secret_rotate` | | GET | `/api/v1/agents/routines/runs` | Your bots' runs, newest first | `agents_bot_run_list` | | GET | `/api/v1/agents/routines/runs/{run_id}` | One of your bots' runs | `agents_bot_run_get` | | GET | `/api/v1/agents/routines/runs/{run_id}/events` | Every item one of your bots' event runs took | `agents_bot_run_event_list` | | POST | `/api/v1/agents/routines/runs/{run_id}/decide` | Approve or decline what a waiting run asks | `agents_bot_run_decide` | | DELETE | `/api/v1/agents/workspaces/{workspace_id}` | Delete a workspace and its files on the daemon | `agents_workspace_delete` | The console's own API under `/api/workspace/agents` mirrors the tools for the signed-in browser session; it does not take API keys. Its routes are listed in [Chats API and MCP tools](/docs/agents/api.md). ## MCP tools {#tools} 48 tools: 21 read, 27 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `agents_approval_decide` | Answer an agent's approval | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/approvals/{approval_id}` | | `agents_attachment_delete` | Remove an unsent upload | write (destructive) | `agents:write` | `DELETE /api/v1/agents/attachments/{file_id}` | | `agents_attachment_list` | List a chat's files | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/attachments` | | `agents_attachment_upload` | Upload a file for a quick chat | write | `agents:write` | `POST /api/v1/agents/attachments` | | `agents_bot_brief_dismiss` | Dismiss the brief | write | `agents:write` | `DELETE /api/v1/agents/bots/brief` | | `agents_bot_brief_get` | What your bots did | read | `agents:read` | `GET /api/v1/agents/bots/brief` | | `agents_bot_create` | Make a bot | write | `agents:write` | `POST /api/v1/agents/bots` | | `agents_bot_delete` | Delete a bot | write (destructive) | `agents:write` | `DELETE /api/v1/agents/bots/{bot_id}` | | `agents_bot_get` | Read a bot | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}` | | `agents_bot_list` | List your bots | read | `agents:read` | `GET /api/v1/agents/bots` | | `agents_bot_memory_get` | Read a bot's memory | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}/memory` | | `agents_bot_memory_update` | Rewrite a bot's memory | write | `agents:write` | `PUT /api/v1/agents/bots/{bot_id}/memory` | | `agents_bot_outreach_decide` | Answer a bot's approval card | write | `agents:write` | `POST /api/v1/agents/bots/{bot_id}/outreach/decide` | | `agents_bot_outreach_get` | How a bot reaches out | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}/outreach` | | `agents_bot_outreach_release` | Let a bot write to someone again | write | `agents:write` | `POST /api/v1/agents/bots/{bot_id}/outreach/release` | | `agents_bot_outreach_update` | Change how a bot reaches out | write | `agents:write` | `PATCH /api/v1/agents/bots/{bot_id}/outreach` | | `agents_bot_routine_create` | Make a bot's routine | write | `agents:write` | `POST /api/v1/agents/routines` | | `agents_bot_routine_delete` | Delete a bot's routine | write (destructive) | `agents:write` | `DELETE /api/v1/agents/routines/{routine_id}` | | `agents_bot_routine_get` | Read a bot's routine | read | `agents:read` | `GET /api/v1/agents/routines/{routine_id}` | | `agents_bot_routine_list` | List a bot's routines | read | `agents:read` | `GET /api/v1/agents/routines` | | `agents_bot_routine_run` | Run a bot's routine now | write | `agents:write` | `POST /api/v1/agents/routines/{routine_id}/run` | | `agents_bot_routine_update` | Change a bot's routine | write | `agents:write` | `PATCH /api/v1/agents/routines/{routine_id}` | | `agents_bot_run_decide` | Answer what a bot asks | write | `agents:write` | `POST /api/v1/agents/routines/runs/{run_id}/decide` | | `agents_bot_run_event_list` | List what started an event run | read | `agents:read` | `GET /api/v1/agents/routines/runs/{run_id}/events` | | `agents_bot_run_get` | Read a bot's run | read | `agents:read` | `GET /api/v1/agents/routines/runs/{run_id}` | | `agents_bot_run_list` | List your bots' runs | read | `agents:read` | `GET /api/v1/agents/routines/runs` | | `agents_bot_secret_rotate` | Rotate a bot routine's secret | write | `agents:write` | `POST /api/v1/agents/routines/{routine_id}/secret` | | `agents_bot_summary_list` | Your bots at a glance | read | `agents:read` | `GET /api/v1/agents/bots/summary` | | `agents_bot_update` | Change a bot | write | `agents:write` | `PATCH /api/v1/agents/bots/{bot_id}` | | `agents_change_get` | List a chat's file changes | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/changes` | | `agents_chat_archive` | Archive a chat | write (destructive) | `agents:write` | `DELETE /api/v1/agents/chats/{chat_id}` | | `agents_chat_create` | Start a chat | write | `agents:write` | `POST /api/v1/agents/chats` | | `agents_chat_get` | Read a chat | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}` | | `agents_chat_list` | List chats | read | `agents:read` | `GET /api/v1/agents/chats` | | `agents_chat_send` | Send a message to a chat | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/messages` | | `agents_chat_stop` | Stop a chat's run | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/abort` | | `agents_chat_update` | Rename a chat, change its mode, gear or servers | write | `agents:write` | `PATCH /api/v1/agents/chats/{chat_id}` | | `agents_connection_create` | Connect a catalog server | write | `agents:write` | `POST /api/v1/agents/connections` | | `agents_connection_delete` | Disconnect a catalog server | write (destructive) | `agents:write` | `DELETE /api/v1/agents/connections/{server}` | | `agents_gear_list` | List the gears a chat can run in | read | `agents:read` | `GET /api/v1/agents/gears` | | `agents_project_list` | List a daemon's projects | read | `agents:read` | `GET /api/v1/agents/projects` | | `agents_question_respond` | Answer an agent's question | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/questions/{question_id}` | | `agents_server_list` | List the servers a quick chat can use | read | `agents:read` | `GET /api/v1/agents/servers` | | `agents_skill_list` | List the skills a quick chat can use | read | `agents:read` | `GET /api/v1/agents/skills` | | `agents_transcript_get` | Read a chat's transcript | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/transcript` | | `agents_workspace_create` | Make a workspace on a daemon | write | `agents:write` | `POST /api/v1/agents/workspaces` | | `agents_workspace_delete` | Delete a workspace | write (destructive) | `agents:write` | `DELETE /api/v1/agents/workspaces/{workspace_id}` | | `agents_workspace_list` | List a daemon's workspaces | read | `agents:read` | `GET /api/v1/agents/workspaces` | Every tool takes `format: "json"` for structured content and refuses arguments it does not list. ## Related {#related} - [Venom Agents](/docs/agents.md) and [Chats API and MCP tools](/docs/agents/api.md). - [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # Build on Admin and the mesh URL: https://cloud.usevenom.dev/docs/developers/admin Description: Run the org's console admin pages from code or an agent (members, budgets, provider keys, routing, webhooks, alerts, audit, daemons and more) with your member role, and find the admin, client and daemon APIs. Venom Admin is the org's console admin pages as `admin_*` MCP tools, each with a REST route under `/api/v1/admin`. It covers members and invitations, spend budgets and the spend cap, provider keys, routing, event webhooks, alerts, the audit log, integrations, guardrails, gears, daemons, API keys, single sign-on groups and more. Each tool calls the same function as the console's own page and the admin API, so the permission check and the audit row are the same, with your credential as the actor. This page also lists the other machine APIs of Venom Cloud that are not MCP: the admin API, the client `/v1` API and the daemon API ([Other admin and mesh APIs](#other-apis)). ## What you can build {#build} - **Spend guards per person or project.** Create a monthly budget that warns at 80 % and blocks at the limit (`POST /api/v1/admin/budgets`), set the org's monthly cap (`PUT /api/v1/admin/spend-cap`), and act on the `budget.warning` and `spend_cap.reached` events. - **Member lifecycle.** Invite people with a role (`admin_invitation_create`), change roles (`admin_member_update`) and remove leavers (`admin_member_remove`). Owners are never changed by a tool. - **Provider key rotation.** Add a provider key you were given (`admin_provider_add`), rotate it with a grace period (`admin_provider_rotate`) and finish or roll back the rotation (`admin_provider_rotation_set`), driven by the `key_rotation.due` event. - **Fleet operations.** List daemons (`GET /api/v1/admin/daemons`), drain or revoke one (`PATCH /api/v1/admin/daemons/{daemon}`), and page someone on `daemon.offline`. - **A compliance trail.** Read the audit log by actor, action prefix or time (`GET /api/v1/admin/audit`) and undo a settings change by its entry id (`admin_audit_undo`). - **Webhook health.** List deliveries (`admin_webhook_delivery_list`), retry a failed one (`admin_webhook_delivery_retry`) and send a test event (`admin_webhook_test`). ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/admin`, server name `venom-admin` | | Connect | `claude mcp add --transport http venom-admin https://cloud.usevenom.dev/workspace/mcp/admin` | | MCP tools | 269 (82 read, 187 write) | | OAuth scopes | `admin:read` `admin:write` | | REST twin | 269 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | `spend_cap.warning`, `spend_cap.reached`, `budget.warning`, `budget.reached`, `spend.threshold`, `spend.forecast`, `spend.anomaly`, `key.expiring`, `key.expired`, `daemon.offline`, `daemon.online`, `autoscale.machine_added`, `autoscale.machine_joined`, `autoscale.machine_draining`, `autoscale.machine_removed`, `autoscale.join_timeout`, `autoscale.machine_interrupted`, `autoscale.cap_reached`, `prompt_filter.blocked`, `quality.degraded`, `quality.recovered`, `prompt_filter.response_blocked`, `chargeback.statement`, `handoff.created`, `handoff.accepted`, `handoff.declined`, `key_rotation.due`, `key_rotation.overdue`, `key_rotation.completed`, `model.retiring`, `price.changed`, `credits.expiring`, `sla.breach`, `sla.credit_drafted` | ## Authentication and scopes {#scopes} The admin tools are the member's role at work, so they need a member: - A **personal API key** acts as its member, with their org role. A read-only personal key only reads. If the member has left the org, the key is refused. - An **OAuth app** acts as the member who connected it. It needs `admin:read` to use the tools at all and `admin:write` to change anything, on top of the member's role. - A **team key** has no member and is refused every admin tool, reads included. Within that, the member's role decides, tool by tool, exactly as on the console page (see [Members and roles](/docs/cloud/console-orgs-members.md)). Some examples: | Tool | Who may | |---|---| | `admin_member_list` | every role (members:read) | | `admin_org_update` | owners and admins (org:manage) | | `admin_member_update`, `admin_member_remove`, `admin_invitation_*` | owners and admins (members:manage) | | `admin_budget_list` | every role (usage:read) | | `admin_budget_create`, `admin_budget_update`, `admin_budget_delete` | owners, admins and billing (org:manage or billing:manage) | | `admin_sso_group_team_set` | owners only (sso:manage) | A refusal answers `403` over REST, or a tool error that says what is missing over MCP. ### What is not a tool {#not-tools} Some admin steps are kept for a person in the console on purpose. Each one is listed in the parity table with its reason. The ones an integrator meets most: - **The owner role.** No tool grants, changes or removes it, and `admin_member_update` and `admin_member_remove` refuse an owner. - **Anything that shows a secret once.** Creating or rotating a Venom API key, minting a daemon join token, creating an event webhook or rotating its signing secret, saving the alerts webhook, and creating or rotating a SCIM token. An agent that could mint these could hand itself access. The tools can revoke or limit them afterwards (`admin_key_delete`, `admin_key_scope_set`, `admin_jointoken_delete`, `admin_webhook_update`, `admin_sso_token_delete`). - **Credentials a person pastes.** The audit export bucket's access key and secret (the export can be tested, run and removed with `admin_audit_export_test`, `admin_audit_export_run` and `admin_audit_export_delete`), the Slack app's credentials, and a GPU cloud's API key. - **Single sign-on cut-over.** Connecting the identity provider, turning SSO on and making it required. - **Prompt and response bodies.** A person with content:read opens them one request at a time. Agents read request metadata with `admin_request_get`. - **Creating an organisation**, and creating or deleting a key group (the cloud operator's admin token only). Provider keys go the other way: an agent may store or rotate a key it was given, and the key is never shown again. ## Worked example {#example} Give one member a $200 monthly budget that warns at 80 % and blocks at the limit. First find their id (`clerk_user_id`): ```bash curl "$VENOM_CLOUD/api/v1/admin/members" -H "Authorization: Bearer $VENOM_API_KEY" curl -X POST "$VENOM_CLOUD/api/v1/admin/budgets" \ -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \ -d '{"scope": "member", "subject": "", "period": "month", "limit_usd": 200, "soft_pct": 80, "action": "block", "name": "Monthly cap"}' ``` The same over MCP, from any client connected to `/workspace/mcp/admin`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "admin_budget_create", "arguments": { "scope": "member", "subject": "", "period": "month", "limit_usd": 200, "soft_pct": 80, "action": "block", "name": "Monthly cap" } } } ``` One budget exists per scope, subject and period. To change the limit later, use `admin_budget_update` with the budget's id from `admin_budget_list`; the scope, subject and period are fixed. With `"action": "downgrade"` and a `downgrade_model`, requests over the limit go to the cheaper model instead of being refused. ## Events {#events} 34 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)). | Event | When | |---|---| | `spend_cap.warning` | The org's month-to-date spend reached 80 % of its monthly cap (once a month per cap). | | `spend_cap.reached` | The monthly cap is reached and requests are refused with 429 spend_cap_reached. | | `budget.warning` | A member, key, team or gear budget reached its warning share of the limit (once per budget and window). | | `budget.reached` | A budget is at its limit: requests are refused with 429 spend_limit_reached, or sent to its cheaper model (once per budget and window). | | `spend.threshold` | A budget's or the monthly cap's spend passed one of the org's alert thresholds (50, 80, 100 % by default; once per threshold and window). | | `spend.forecast` | At the current rate a budget or the monthly cap runs out before its window ends (once per window and limit). | | `spend.anomaly` | A key, member, model or gear spent far above its usual for the hour (robust hourly baseline, the org's floor and sensitivity), with the top requests and keys and a link to pause the key. | | `key.expiring` | An API key expires within 7 days (once per key and expiry). | | `key.expired` | An API key passed its expiry and no longer works. | | `daemon.offline` | A daemon stopped heartbeating: its lease lapsed more than 2 minutes ago. | | `daemon.online` | A daemon reported offline is heartbeating again. | | `autoscale.machine_added` | A pool asked its GPU cloud for a machine (demand, its floor or schedule, or Scale to N). | | `autoscale.machine_joined` | A pool's machine booted and its daemon joined the org. | | `autoscale.machine_draining` | A pool's machine stopped taking new requests before it is removed (idle, or scaled down). | | `autoscale.machine_removed` | A pool's machine was terminated at its GPU cloud, or vanished there. | | `autoscale.join_timeout` | A pool's machine did not join in time and was terminated; check the image and boot log. | | `autoscale.machine_interrupted` | A GPU cloud reclaimed a pool's spot or preemptible machine; its jobs were requeued and a replacement launched elsewhere. | | `autoscale.cap_reached` | A pool's estimated GPU spend reached its monthly cap; it adds no machines until next month. | | `prompt_filter.blocked` | A prompt filter refused a request (at most once per rule and key every 10 minutes). | | `quality.degraded` | Scheduled quality checks found a significant drop in a model's score or a rise in its latency on a suite. | | `quality.recovered` | A model flagged degraded is back near its baseline on that suite. | | `prompt_filter.response_blocked` | A response filter stopped a model's answer mid-way (at most once per rule and key every 10 minutes). | | `chargeback.statement` | Last month's spend per team, project, gear, key or member, sent on the 1st (UTC) when the monthly statement is on (Usage, Chargeback). | | `handoff.created` | A member handed a venom session to a teammate or a team (/handoff): who, to whom, the repository and branch; never the note. | | `handoff.accepted` | The recipient of a handoff accepted it (venom handoff accept) and took the session over. | | `handoff.declined` | The recipient of a handoff declined it. | | `key_rotation.due` | A provider key or API key reaches its rotation date within 14 days (the org's schedule or the key's own; once per key version). Names and last four characters only. | | `key_rotation.overdue` | A provider key or API key is past its rotation date (once per key version). | | `key_rotation.completed` | A rotated provider key's old key stopped serving after its grace period (or an admin retired it). Revoke it at the provider. | | `model.retiring` | A model the org's gears, routing rows or allow lists use retires within the org's warning window (30 days by default) or is gone from its provider's list (once per model and date). | | `price.changed` | The effective price of a model used in the last 30 days changed (a price table update, a custom price, a catalog sync): old and new price and the monthly impact at the last 30 days' use. | | `credits.expiring` | Prepaid credits or a free quota on a provider key expire within 7 days with a balance left (once per credit and expiry). Key name and amounts only. | | `sla.breach` | A customer's or route's service-level target (availability, p95 time to first token, error rate) is missed this month so far (once per target and month): the figures, the target and a link to the SLA page. | | `sla.credit_drafted` | A finished month breached a customer's SLA and a service credit was drafted for its next invoice; an admin approves it first (once per target and month). | Endpoints are created in the console (Settings, Webhooks), because creating one shows its signing secret once. After that, the `admin_webhook_*` tools list, change, test and delete them, and read and retry deliveries. Payloads and the signature are described in [Webhooks and events](/docs/developers/webhooks.md). ## REST routes {#rest} The REST twin: 269 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). **/admin/org** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/admin/org` | Rename the organisation (its display name only) | `admin_org_update` | **/admin/members** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/members` | List the org's members and pending invitations | `admin_member_list` | | PATCH | `/api/v1/admin/members/{member}` | Change a member's role (never to or from owner) | `admin_member_update` | | DELETE | `/api/v1/admin/members/{member}` | Remove a member (never an owner) | `admin_member_remove` | **/admin/invitations** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/admin/invitations` | Invite someone by email with a role (never owner) | `admin_invitation_create` | | DELETE | `/api/v1/admin/invitations/{invitation}` | Revoke a pending invitation | `admin_invitation_delete` | **/admin/budgets** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/budgets` | List spend budgets with live spend | `admin_budget_list` | | POST | `/api/v1/admin/budgets` | Create a spend budget | `admin_budget_create` | | PATCH | `/api/v1/admin/budgets/{budget}` | Change a spend budget | `admin_budget_update` | | DELETE | `/api/v1/admin/budgets/{budget}` | Delete a spend budget | `admin_budget_delete` | **/admin/providers** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/providers` | List provider keys | `admin_provider_list` | | POST | `/api/v1/admin/providers` | Add a provider key | `admin_provider_add` | | PATCH | `/api/v1/admin/providers/{key_id}` | Change a provider key | `admin_provider_update` | | DELETE | `/api/v1/admin/providers/{key_id}` | Delete a provider key | `admin_provider_delete` | | POST | `/api/v1/admin/providers/{key_id}/rotate` | Rotate a provider key | `admin_provider_rotate` | | POST | `/api/v1/admin/providers/{key_id}/rotation` | Finish or roll back a key rotation | `admin_provider_rotation_set` | | POST | `/api/v1/admin/providers/reorder` | Order a provider's keys | `admin_provider_reorder` | | POST | `/api/v1/admin/providers/{key_id}/test` | Check a stored provider key | `admin_provider_test` | **/admin/platform-keys** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/admin/platform-keys` | Use Venom's keys after yours | `admin_platform_keys_set` | **/admin/routing** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/routing` | Read the routing policy | `admin_routing_get` | | PUT | `/api/v1/admin/routing` | Set a routing policy | `admin_routing_set` | | DELETE | `/api/v1/admin/routing` | Remove a routing policy | `admin_routing_delete` | | GET | `/api/v1/admin/routing/preview` | Preview how a model routes | `admin_routing_preview` | | POST | `/api/v1/admin/routing/trusted` | Trust a public node | `admin_routing_trusted_add` | | DELETE | `/api/v1/admin/routing/trusted/{daemon_id}` | Stop trusting a public node | `admin_routing_trusted_remove` | **/admin/auto-routing** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/auto-routing` | Read model choice (auto routing) | `admin_autorouting_get` | | PUT | `/api/v1/admin/auto-routing` | Set model choice (auto routing) | `admin_autorouting_set` | | DELETE | `/api/v1/admin/auto-routing` | Reset model choice to defaults | `admin_autorouting_delete` | | POST | `/api/v1/admin/auto-routing/test` | Test model choice on a prompt | `admin_autorouting_test` | **/admin/webhooks** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/webhooks` | List event webhooks | `admin_webhook_list` | | PATCH | `/api/v1/admin/webhooks/{endpoint}` | Change an event webhook | `admin_webhook_update` | | DELETE | `/api/v1/admin/webhooks/{endpoint}` | Delete an event webhook | `admin_webhook_delete` | | POST | `/api/v1/admin/webhooks/{endpoint}/test` | Send a test event | `admin_webhook_test` | **/admin/webhook-deliveries** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/webhook-deliveries` | List webhook deliveries | `admin_webhook_delivery_list` | | POST | `/api/v1/admin/webhook-deliveries/{delivery}/retry` | Retry a webhook delivery | `admin_webhook_delivery_retry` | **/admin/alerts** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/alerts` | List alerts | `admin_alert_list` | | POST | `/api/v1/admin/alerts` | Create an alert | `admin_alert_create` | | PATCH | `/api/v1/admin/alerts/{alert}` | Pause or resume an alert | `admin_alert_update` | | DELETE | `/api/v1/admin/alerts/{alert}` | Delete an alert | `admin_alert_delete` | **/admin/alert-hits** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/alert-hits` | List alert hits | `admin_alert_hit_list` | **/admin/alert-webhook** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/admin/alert-webhook` | Remove the alerts webhook | `admin_alert_webhook_delete` | | POST | `/api/v1/admin/alert-webhook/test` | Test the alerts webhook | `admin_alert_webhook_test` | **/admin/audit** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/audit` | List the audit log | `admin_audit_list` | | POST | `/api/v1/admin/audit/{entry}/undo` | Undo a settings change | `admin_audit_undo` | **/admin/audit-export** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/admin/audit-export/test` | Test the audit export | `admin_audit_export_test` | | POST | `/api/v1/admin/audit-export/run` | Export the audit log now | `admin_audit_export_run` | | DELETE | `/api/v1/admin/audit-export` | Remove the audit export | `admin_audit_export_delete` | **/admin/integrations** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/integrations` | List integrations | `admin_integration_list` | | POST | `/api/v1/admin/integrations` | Start an integration | `admin_integration_create` | | PATCH | `/api/v1/admin/integrations/{integration}` | Change an integration | `admin_integration_update` | | DELETE | `/api/v1/admin/integrations/{integration}` | Disconnect an integration | `admin_integration_delete` | | POST | `/api/v1/admin/integrations/{integration}/check` | Check a Slack integration | `admin_integration_test` | | PUT | `/api/v1/admin/integrations/{integration}/channels` | Set a Slack channel's gear | `admin_integration_channel_set` | | DELETE | `/api/v1/admin/integrations/{integration}/channels` | Clear a Slack channel's gear | `admin_integration_channel_delete` | | DELETE | `/api/v1/admin/integrations/{integration}/members` | Unlink a Slack user | `admin_integration_member_unlink` | **/admin/guardrails** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/guardrails` | List guardrails | `admin_guardrail_list` | | POST | `/api/v1/admin/guardrails` | Add a guardrail | `admin_guardrail_create` | | PATCH | `/api/v1/admin/guardrails/{code}` | Change a guardrail | `admin_guardrail_update` | | DELETE | `/api/v1/admin/guardrails/{code}` | Remove a guardrail | `admin_guardrail_delete` | | PUT | `/api/v1/admin/guardrails/overrides` | Override an org guardrail for a team | `admin_guardrail_override_set` | | POST | `/api/v1/admin/guardrails/test` | Test guardrails on text | `admin_guardrail_test` | | POST | `/api/v1/admin/guardrails/draft` | Draft a guardrail from a sentence | `admin_guardrail_draft` | | POST | `/api/v1/admin/guardrails/suggestions/{suggestion}` | Decide a suggested guardrail | `admin_guardrail_suggestion_decide` | **/admin/guardrail-drafting** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/admin/guardrail-drafting` | Set guardrail drafting | `admin_guardrail_drafting_set` | **/admin/injection-classifier** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/admin/injection-classifier` | Set the injection shield classifier | `admin_guardrail_shield_set` | **/admin/teams** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/teams/{team}/permissions` | Read a team's permission profile | `admin_team_permissions_get` | | PUT | `/api/v1/admin/teams/{team}/permissions` | Set a team's permission profile | `admin_team_permissions_set` | | GET | `/api/v1/admin/teams` | List teams | `admin_team_list` | **/admin/gears** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/gears` | List gears | `admin_gear_list` | | PUT | `/api/v1/admin/gears` | Save gears | `admin_gear_set` | **/admin/daemons** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/daemons` | List daemons | `admin_daemon_list` | | PATCH | `/api/v1/admin/daemons/{daemon}` | Change a daemon | `admin_daemon_update` | | GET | `/api/v1/admin/daemons/{daemon}/shares` | List a daemon's shares | `admin_daemon_share_list` | | PUT | `/api/v1/admin/daemons/{daemon}/shares` | Set a daemon's shares | `admin_daemon_share_set` | **/admin/prewarm** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/prewarm` | Read the prewarm schedule | `admin_prewarm_get` | | PUT | `/api/v1/admin/prewarm` | Save the prewarm schedule | `admin_prewarm_set` | | DELETE | `/api/v1/admin/prewarm` | Remove the prewarm schedule | `admin_prewarm_delete` | | POST | `/api/v1/admin/prewarm/run` | Prewarm now | `admin_prewarm_run` | **/admin/grants** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/grants` | List GPU grants | `admin_grant_list` | | POST | `/api/v1/admin/grants` | Share daemons with a team | `admin_grant_create` | | PATCH | `/api/v1/admin/grants/{grant}` | Change a GPU grant | `admin_grant_update` | | DELETE | `/api/v1/admin/grants/{grant}` | Revoke a GPU grant | `admin_grant_delete` | **/admin/handoffs** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/handoffs` | List session handoffs | `admin_handoff_list` | | POST | `/api/v1/admin/handoffs/{handoff}/decline` | Decline a handoff | `admin_handoff_respond` | | DELETE | `/api/v1/admin/handoffs/{handoff}` | Cancel a handoff | `admin_handoff_delete` | **/admin/live-sessions** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/live-sessions` | List live sessions | `admin_live_list` | | PATCH | `/api/v1/admin/live-sessions/{session}` | Change who can use a live session | `admin_live_update` | | DELETE | `/api/v1/admin/live-sessions/{session}` | Stop a live session | `admin_live_stop` | **/admin/shares** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/shares` | List shared sessions | `admin_share_list` | | PATCH | `/api/v1/admin/shares/{share}` | Change a shared session | `admin_share_update` | | DELETE | `/api/v1/admin/shares/{share}` | Delete a shared session | `admin_share_delete` | | DELETE | `/api/v1/admin/shares/{share}/public-link` | Revoke a shared session's public link | `admin_share_link_delete` | | POST | `/api/v1/admin/shares/{share}/comments` | Comment on a shared session | `admin_share_comment_create` | | DELETE | `/api/v1/admin/shares/{share}/comments` | Delete a share comment | `admin_share_comment_delete` | **/admin/session-sharing** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/session-sharing` | Read session sharing settings | `admin_sharing_get` | | PUT | `/api/v1/admin/session-sharing` | Set session sharing settings | `admin_sharing_set` | **/admin/session-summaries** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/session-summaries` | Read session summary settings | `admin_session_summaries_get` | | PUT | `/api/v1/admin/session-summaries` | Set session summary settings | `admin_session_summaries_set` | **/admin/requests** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/requests/{request}` | Read a request's trace | `admin_request_get` | **/admin/chargeback-schedule** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/chargeback-schedule` | Read the monthly statement schedule | `admin_chargeback_schedule_get` | | PUT | `/api/v1/admin/chargeback-schedule` | Set the monthly statement schedule | `admin_chargeback_schedule_set` | **/admin/savings** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/savings` | Read savings suggestions | `admin_savings_get` | | POST | `/api/v1/admin/savings/apply` | Apply a savings tier | `admin_savings_apply` | | PUT | `/api/v1/admin/savings/commitments` | Set commitment prices | `admin_savings_commitments_set` | **/admin/quality** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/quality` | Read quality checks | `admin_quality_get` | | PUT | `/api/v1/admin/quality` | Set quality checks | `admin_quality_set` | | POST | `/api/v1/admin/quality/suites` | Create a quality suite | `admin_quality_suite_create` | | PATCH | `/api/v1/admin/quality/suites/{suite}` | Change a quality suite | `admin_quality_suite_update` | | DELETE | `/api/v1/admin/quality/suites/{suite}` | Delete a quality suite | `admin_quality_suite_delete` | | POST | `/api/v1/admin/quality/test` | Test one quality case | `admin_quality_test` | **/admin/memory** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/memory` | List shared memory | `admin_memory_list` | | POST | `/api/v1/admin/memory` | Add a memory | `admin_memory_create` | | PATCH | `/api/v1/admin/memory/{memory}` | Edit a memory | `admin_memory_update` | | DELETE | `/api/v1/admin/memory/{memory}` | Delete a memory | `admin_memory_delete` | | POST | `/api/v1/admin/memory/{memory}/approve` | Approve a proposed memory | `admin_memory_approve` | | POST | `/api/v1/admin/memory/{memory}/reject` | Reject a proposed memory | `admin_memory_reject` | | POST | `/api/v1/admin/memory/{memory}/confirm` | Confirm a memory is still true | `admin_memory_confirm` | **/admin/spend-alerts** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/spend-alerts` | List spend alerts | `admin_spendalert_list` | | PUT | `/api/v1/admin/spend-alerts` | Set spend alert settings | `admin_spendalert_set` | **/admin/keys** | Method | Path | Summary | MCP tool | |---|---|---|---| | PATCH | `/api/v1/admin/keys/{key_id}` | Pause or resume a Venom API key | `admin_key_update` | | DELETE | `/api/v1/admin/keys/{key_id}` | Revoke a Venom API key | `admin_key_delete` | | GET | `/api/v1/admin/keys` | List Venom API keys | `admin_key_list` | | PATCH | `/api/v1/admin/keys/{key_id}/scope` | Set a key's scope | `admin_key_scope_set` | **/admin/logging** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/logging` | Read request logging settings | `admin_logging_get` | | PUT | `/api/v1/admin/logging` | Set request logging | `admin_logging_set` | **/admin/key-rotation** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/key-rotation` | Read the key rotation policy | `admin_keyrotation_get` | | PUT | `/api/v1/admin/key-rotation` | Set the key rotation policy | `admin_keyrotation_set` | **/admin/sso** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/sso` | Read single sign-on | `admin_sso_get` | | PUT | `/api/v1/admin/sso/provisioning` | Set SSO provisioning | `admin_sso_provisioning_set` | | POST | `/api/v1/admin/sso/domains` | Add an SSO domain | `admin_sso_domain_add` | | POST | `/api/v1/admin/sso/domains/{domain_id}/validate` | Verify an SSO domain | `admin_sso_domain_validate` | | DELETE | `/api/v1/admin/sso/domains/{domain_id}` | Remove an SSO domain | `admin_sso_domain_delete` | | GET | `/api/v1/admin/sso/groups` | List SCIM groups | `admin_sso_group_list` | | PUT | `/api/v1/admin/sso/groups/{group_id}/team` | Sync a SCIM group into a team | `admin_sso_group_team_set` | | DELETE | `/api/v1/admin/sso/tokens/{token_id}` | Revoke a SCIM token | `admin_sso_token_delete` | **/admin/knowledge** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/admin/knowledge/ask` | Ask the organisation's knowledge | `admin_knowledge_ask` | **/admin/autopilot** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/autopilot` | Read the local autopilot | `admin_autopilot_get` | | PUT | `/api/v1/admin/autopilot` | Set autopilot shadow evaluation | `admin_autopilot_set` | | POST | `/api/v1/admin/autopilot/apply` | Apply an autopilot suggestion | `admin_autopilot_apply` | | POST | `/api/v1/admin/autopilot/revert` | Revert an autopilot change | `admin_autopilot_revert` | **/admin/autoscale** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/autoscale` | List autoscaling | `admin_autoscale_list` | | POST | `/api/v1/admin/autoscale/clouds/{cloud}/refresh` | Refresh a connected GPU cloud | `admin_cloud_refresh` | | DELETE | `/api/v1/admin/autoscale/clouds/{cloud}` | Disconnect a GPU cloud | `admin_cloud_delete` | | DELETE | `/api/v1/admin/autoscale/pools/{pool}` | Delete an autoscaling pool | `admin_pool_delete` | | POST | `/api/v1/admin/autoscale/machines/{machine}/drain` | Drain an autoscaled machine | `admin_machine_stop` | | DELETE | `/api/v1/admin/autoscale/machines/{machine}` | Terminate an autoscaled machine | `admin_machine_delete` | **/admin/evals** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/evals` | List evals | `admin_eval_list` | | GET | `/api/v1/admin/evals/runs/{run}` | Read an eval run | `admin_eval_run_get` | | POST | `/api/v1/admin/evals/runs` | Queue an eval run | `admin_eval_run_create` | | POST | `/api/v1/admin/evals/runs/{run}/cancel` | Cancel an eval run | `admin_eval_run_cancel` | | POST | `/api/v1/admin/evals/suggestions/{suggestion}/dismiss` | Dismiss an eval suggestion | `admin_eval_suggestion_dismiss` | | DELETE | `/api/v1/admin/evals/runners/{runner}` | Remove an eval runner | `admin_eval_runner_delete` | | POST | `/api/v1/admin/evals/golden` | Add a golden task | `admin_eval_golden_create` | | PUT | `/api/v1/admin/evals/golden/{golden}` | Change a golden task | `admin_eval_golden_update` | | DELETE | `/api/v1/admin/evals/golden/{golden}` | Delete a golden task | `admin_eval_golden_delete` | **/admin/library** | Method | Path | Summary | MCP tool | |---|---|---|---| | POST | `/api/v1/admin/library/{item}/test` | Test a library change | `admin_library_test` | | GET | `/api/v1/admin/library` | List the library | `admin_library_list` | | POST | `/api/v1/admin/library` | Add a library item | `admin_library_create` | | GET | `/api/v1/admin/library/{item}` | Read a library item | `admin_library_get` | | PATCH | `/api/v1/admin/library/{item}` | Change a library item | `admin_library_update` | | DELETE | `/api/v1/admin/library/{item}` | Delete a library item | `admin_library_delete` | | GET | `/api/v1/admin/library/{item}/version` | Read a library version | `admin_library_version_get` | | POST | `/api/v1/admin/library/{item}/publish` | Publish a library draft | `admin_library_publish` | | POST | `/api/v1/admin/library/{item}/rollback` | Roll a library item back | `admin_library_rollback` | **/admin/experiments** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/experiments` | List gear experiments | `admin_experiment_list` | | POST | `/api/v1/admin/experiments` | Start a gear experiment | `admin_experiment_create` | | GET | `/api/v1/admin/experiments/{experiment}` | Read a gear experiment | `admin_experiment_get` | | DELETE | `/api/v1/admin/experiments/{experiment}` | Delete a gear experiment | `admin_experiment_delete` | | POST | `/api/v1/admin/experiments/{experiment}/stop` | Stop a gear experiment | `admin_experiment_stop` | | POST | `/api/v1/admin/experiments/{experiment}/apply` | Make an experiment's gear the default | `admin_experiment_apply` | **/admin/prompt-tests** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/prompt-tests` | List prompt tests | `admin_prompttest_list` | | POST | `/api/v1/admin/prompt-tests` | Start a prompt test | `admin_prompttest_create` | | GET | `/api/v1/admin/prompt-tests/{test}` | Read a prompt test | `admin_prompttest_get` | | DELETE | `/api/v1/admin/prompt-tests/{test}` | Delete a prompt test | `admin_prompttest_delete` | | POST | `/api/v1/admin/prompt-tests/{test}/stop` | Stop a prompt test | `admin_prompttest_stop` | | POST | `/api/v1/admin/prompt-tests/{test}/apply` | Publish a prompt test's winner | `admin_prompttest_apply` | **/admin/failures** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/failures` | List session failures | `admin_failure_list` | | GET | `/api/v1/admin/failures/settings` | Read failure classifier settings | `admin_failure_settings_get` | | PUT | `/api/v1/admin/failures/settings` | Set the failure classifier | `admin_failure_settings_set` | | POST | `/api/v1/admin/failures/classify` | Classify failures now | `admin_failure_run` | **/admin/filters** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/filters` | List prompt filters | `admin_filter_list` | | PUT | `/api/v1/admin/filters` | Replace the prompt filters | `admin_filter_set` | | POST | `/api/v1/admin/filters/test` | Test prompt filters on text | `admin_filter_test` | **/admin/secret-scanner** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/secret-scanner` | Read the secret scanner | `admin_scanner_get` | | PUT | `/api/v1/admin/secret-scanner` | Set the secret scanner | `admin_scanner_set` | **/admin/intake** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/intake` | Read issue intake | `admin_intake_get` | | POST | `/api/v1/admin/intake/jobs/{job}/cancel` | Cancel an intake job | `admin_intake_job_cancel` | | POST | `/api/v1/admin/intake/jobs/{job}/retry` | Retry an intake job | `admin_intake_job_retry` | | DELETE | `/api/v1/admin/intake/runners/{runner}` | Remove an intake runner | `admin_intake_runner_delete` | **/admin/lifecycle** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/lifecycle` | Read model lifecycle | `admin_lifecycle_get` | | POST | `/api/v1/admin/lifecycle/switch` | Switch gears off a retiring model | `admin_lifecycle_apply` | | PUT | `/api/v1/admin/lifecycle/settings` | Set lifecycle warnings | `admin_lifecycle_set` | | POST | `/api/v1/admin/lifecycle/credits` | Add a provider credit | `admin_credit_create` | | PATCH | `/api/v1/admin/lifecycle/credits/{credit}` | Change a provider credit | `admin_credit_update` | | DELETE | `/api/v1/admin/lifecycle/credits/{credit}` | Remove a provider credit | `admin_credit_delete` | | POST | `/api/v1/admin/lifecycle/credits/{credit}/refresh` | Read a credit's balance from its provider | `admin_credit_refresh` | **/admin/skills** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/skills` | List the org's skills | `admin_skill_list` | | POST | `/api/v1/admin/skills` | Add a skill from text | `admin_skill_create` | | GET | `/api/v1/admin/skills/{skill}` | Read a skill | `admin_skill_get` | | PATCH | `/api/v1/admin/skills/{skill}` | Change a skill | `admin_skill_update` | | DELETE | `/api/v1/admin/skills/{skill}` | Delete a skill | `admin_skill_delete` | | POST | `/api/v1/admin/skills/export` | Download skills as a zip (its url, and the file as base64 when it fits) | `admin_skill_export` | | GET | `/api/v1/admin/skills/{skill}/version` | Read a skill version | `admin_skill_version_get` | | POST | `/api/v1/admin/skills/import` | Import a skill from a URL | `admin_skill_import` | | POST | `/api/v1/admin/skills/source` | See the skills a URL holds | `admin_skill_source_preview` | | POST | `/api/v1/admin/skills/source/import` | Import several skills from a URL | `admin_skill_source_import` | | POST | `/api/v1/admin/skills/bulk` | Change several skills | `admin_skill_bulk_update` | | POST | `/api/v1/admin/skills/bulk/delete` | Delete several skills | `admin_skill_bulk_delete` | | PUT | `/api/v1/admin/skills/{skill}/scope` | Set who gets a skill | `admin_skill_scope_set` | | POST | `/api/v1/admin/skills/{skill}/check` | Check a skill's source for updates | `admin_skill_refresh` | | POST | `/api/v1/admin/skills/{skill}/approve` | Approve a skill's pending update | `admin_skill_approve` | | POST | `/api/v1/admin/skills/{skill}/reject` | Reject a skill's pending update | `admin_skill_reject` | | POST | `/api/v1/admin/skills/{skill}/publish` | Turn a skill on | `admin_skill_publish` | | POST | `/api/v1/admin/skills/{skill}/disable` | Turn a skill off | `admin_skill_disable` | | POST | `/api/v1/admin/skills/{skill}/rollback` | Roll a skill back | `admin_skill_rollback` | **/admin/mcp-servers** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/mcp-servers` | List the org's own MCP servers | `admin_mcpserver_list` | | POST | `/api/v1/admin/mcp-servers` | Add an MCP server by URL | `admin_mcpserver_create` | | GET | `/api/v1/admin/mcp-servers/{server}` | Read one of the org's MCP servers | `admin_mcpserver_get` | | PATCH | `/api/v1/admin/mcp-servers/{server}` | Change one of the org's MCP servers | `admin_mcpserver_update` | | DELETE | `/api/v1/admin/mcp-servers/{server}` | Remove one of the org's MCP servers | `admin_mcpserver_delete` | | POST | `/api/v1/admin/mcp-servers/test` | Test an MCP server's connection | `admin_mcpserver_test` | **/admin/mcp-catalog** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/mcp-catalog` | List the MCP server catalog | `admin_mcp_catalog_list` | **/admin/bots** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/bots` | List the organisation's bots | `admin_bot_list` | | GET | `/api/v1/admin/bots/{bot}` | Read one bot in the register | `admin_bot_get` | **/admin/me** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/me/guardrails` | List my guardrails | `admin_myguardrail_list` | | POST | `/api/v1/admin/me/guardrails` | Add my guardrail | `admin_myguardrail_create` | | PATCH | `/api/v1/admin/me/guardrails/{code}` | Change my guardrail | `admin_myguardrail_update` | | DELETE | `/api/v1/admin/me/guardrails/{code}` | Remove my guardrail | `admin_myguardrail_delete` | | PUT | `/api/v1/admin/me/guardrails/overrides` | Switch a guardrail for me | `admin_myguardrail_set` | | POST | `/api/v1/admin/me/guardrails/{code}/suggest` | Suggest a guardrail to a team | `admin_myguardrail_request` | | POST | `/api/v1/admin/me/guardrails/draft` | Draft a personal guardrail | `admin_myguardrail_draft` | | POST | `/api/v1/admin/me/guardrails/test` | Test my guardrails on text | `admin_myguardrail_test` | **/admin/onboarding** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/onboarding` | List onboarding paths | `admin_onboarding_list` | | POST | `/api/v1/admin/onboarding` | Create an onboarding path | `admin_onboarding_create` | | PATCH | `/api/v1/admin/onboarding/{path}` | Change an onboarding path | `admin_onboarding_update` | | DELETE | `/api/v1/admin/onboarding/{path}` | Delete an onboarding path | `admin_onboarding_delete` | | POST | `/api/v1/admin/onboarding/{path}/steps` | Mark an onboarding step | `admin_onboarding_mark` | **/admin/packs** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/packs` | List starter packs | `admin_pack_list` | | GET | `/api/v1/admin/packs/{pack}` | Read a starter pack | `admin_pack_get` | | POST | `/api/v1/admin/packs/{pack}` | Install a starter pack | `admin_pack_apply` | | DELETE | `/api/v1/admin/packs/{pack}` | Uninstall a starter pack | `admin_pack_remove` | **/admin/redteam** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/redteam` | Read red team results | `admin_redteam_get` | | GET | `/api/v1/admin/redteam/runs/{run}` | Read a red team run | `admin_redteam_run_get` | | POST | `/api/v1/admin/redteam/runs` | Run the red team corpus | `admin_redteam_run` | **/admin/failover-drill** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/failover-drill` | Read failover drill options | `admin_drill_get` | | POST | `/api/v1/admin/failover-drill` | Plan a failover drill | `admin_drill_run` | **/admin/scorecard** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/scorecard` | Read the scorecard | `admin_scorecard_get` | **/admin/session-outcomes** | Method | Path | Summary | MCP tool | |---|---|---|---| | PUT | `/api/v1/admin/session-outcomes` | Set session outcome tracking | `admin_outcomes_set` | **/admin/shadow** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/shadow` | Read shadow routing | `admin_shadow_get` | | PUT | `/api/v1/admin/shadow` | Set shadow routing | `admin_shadow_set` | | GET | `/api/v1/admin/shadow/tests/{test}` | Read a shadow test | `admin_shadowtest_get` | | PATCH | `/api/v1/admin/shadow/tests/{test}` | Change a shadow test | `admin_shadowtest_update` | | DELETE | `/api/v1/admin/shadow/tests/{test}` | Delete a shadow test | `admin_shadowtest_delete` | | POST | `/api/v1/admin/shadow/tests` | Start a shadow test | `admin_shadowtest_create` | | POST | `/api/v1/admin/shadow/tests/{test}/apply` | Switch gears to a shadow test's candidate | `admin_shadowtest_apply` | | POST | `/api/v1/admin/shadow/tests/{test}/revert` | Revert a shadow test's switch | `admin_shadowtest_revert` | **/admin/model-access** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/model-access` | Read model access by role | `admin_modelaccess_get` | | PUT | `/api/v1/admin/model-access` | Set model access by role | `admin_modelaccess_set` | **/admin/spend-cap** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/spend-cap` | Read the org spend cap | `admin_spendcap_get` | | PUT | `/api/v1/admin/spend-cap` | Set the org spend cap | `admin_spendcap_set` | **/admin/spend** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/spend/limits` | List every AI limit and this period's spend | `admin_spendlimit_list` | | PUT | `/api/v1/admin/spend/limits/{limit}` | Change one AI limit | `admin_spendlimit_set` | **/admin/session-guard** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/session-guard` | Read session guard limits | `admin_sessionguard_get` | | PUT | `/api/v1/admin/session-guard` | Set session guard limits | `admin_sessionguard_set` | **/admin/session-pauses** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/session-pauses` | List paused sessions | `admin_pause_list` | | POST | `/api/v1/admin/session-pauses/{pause}/resume` | Resume a paused session | `admin_pause_update` | **/admin/join-tokens** | Method | Path | Summary | MCP tool | |---|---|---|---| | DELETE | `/api/v1/admin/join-tokens/{jointoken}` | Delete a daemon join token | `admin_jointoken_delete` | **/admin/search** | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/admin/search` | Read the search settings | `admin_search_get` | | PUT | `/api/v1/admin/search` | Change the search settings | `admin_search_set` | ## MCP tools {#tools} 269 tools: 82 read, 187 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `admin_alert_create` | Create an alert | write | `admin:write` | `POST /api/v1/admin/alerts` | | `admin_alert_delete` | Delete an alert | write (destructive) | `admin:write` | `DELETE /api/v1/admin/alerts/{alert}` | | `admin_alert_hit_list` | List alert hits | read | `admin:read` | `GET /api/v1/admin/alert-hits` | | `admin_alert_list` | List alerts | read | `admin:read` | `GET /api/v1/admin/alerts` | | `admin_alert_update` | Pause or resume an alert | write | `admin:write` | `PATCH /api/v1/admin/alerts/{alert}` | | `admin_alert_webhook_delete` | Remove the alerts webhook | write (destructive) | `admin:write` | `DELETE /api/v1/admin/alert-webhook` | | `admin_alert_webhook_test` | Test the alerts webhook | write | `admin:write` | `POST /api/v1/admin/alert-webhook/test` | | `admin_audit_export_delete` | Remove the audit export | write (destructive) | `admin:write` | `DELETE /api/v1/admin/audit-export` | | `admin_audit_export_run` | Export the audit log now | write | `admin:write` | `POST /api/v1/admin/audit-export/run` | | `admin_audit_export_test` | Test the audit export | write | `admin:write` | `POST /api/v1/admin/audit-export/test` | | `admin_audit_list` | List the audit log | read | `admin:read` | `GET /api/v1/admin/audit` | | `admin_audit_undo` | Undo a settings change | write | `admin:write` | `POST /api/v1/admin/audit/{entry}/undo` | | `admin_autopilot_apply` | Apply an autopilot suggestion | write | `admin:write` | `POST /api/v1/admin/autopilot/apply` | | `admin_autopilot_get` | Read the local autopilot | read | `admin:read` | `GET /api/v1/admin/autopilot` | | `admin_autopilot_revert` | Revert an autopilot change | write | `admin:write` | `POST /api/v1/admin/autopilot/revert` | | `admin_autopilot_set` | Set autopilot shadow evaluation | write | `admin:write` | `PUT /api/v1/admin/autopilot` | | `admin_autorouting_delete` | Reset model choice to defaults | write (destructive) | `admin:write` | `DELETE /api/v1/admin/auto-routing` | | `admin_autorouting_get` | Read model choice (auto routing) | read | `admin:read` | `GET /api/v1/admin/auto-routing` | | `admin_autorouting_set` | Set model choice (auto routing) | write | `admin:write` | `PUT /api/v1/admin/auto-routing` | | `admin_autorouting_test` | Test model choice on a prompt | read | `admin:read` | `POST /api/v1/admin/auto-routing/test` | | `admin_autoscale_list` | List autoscaling | read | `admin:read` | `GET /api/v1/admin/autoscale` | | `admin_bot_get` | Read one bot in the register | read | `admin:read` | `GET /api/v1/admin/bots/{bot}` | | `admin_bot_list` | List the organisation's bots | read | `admin:read` | `GET /api/v1/admin/bots` | | `admin_budget_create` | Create a spend budget | write | `admin:write` | `POST /api/v1/admin/budgets` | | `admin_budget_delete` | Delete a spend budget | write (destructive) | `admin:write` | `DELETE /api/v1/admin/budgets/{budget}` | | `admin_budget_list` | List spend budgets | read | `admin:read` | `GET /api/v1/admin/budgets` | | `admin_budget_update` | Change a spend budget | write | `admin:write` | `PATCH /api/v1/admin/budgets/{budget}` | | `admin_chargeback_schedule_get` | Read the monthly statement schedule | read | `admin:read` | `GET /api/v1/admin/chargeback-schedule` | | `admin_chargeback_schedule_set` | Set the monthly statement schedule | write | `admin:write` | `PUT /api/v1/admin/chargeback-schedule` | | `admin_cloud_delete` | Disconnect a GPU cloud | write (destructive) | `admin:write` | `DELETE /api/v1/admin/autoscale/clouds/{cloud}` | | `admin_cloud_refresh` | Refresh a connected GPU cloud | write | `admin:write` | `POST /api/v1/admin/autoscale/clouds/{cloud}/refresh` | | `admin_credit_create` | Add a provider credit | write | `admin:write` | `POST /api/v1/admin/lifecycle/credits` | | `admin_credit_delete` | Remove a provider credit | write (destructive) | `admin:write` | `DELETE /api/v1/admin/lifecycle/credits/{credit}` | | `admin_credit_refresh` | Read a credit's balance from its provider | write | `admin:write` | `POST /api/v1/admin/lifecycle/credits/{credit}/refresh` | | `admin_credit_update` | Change a provider credit | write | `admin:write` | `PATCH /api/v1/admin/lifecycle/credits/{credit}` | | `admin_daemon_list` | List daemons | read | `admin:read` | `GET /api/v1/admin/daemons` | | `admin_daemon_share_list` | List a daemon's shares | read | `admin:read` | `GET /api/v1/admin/daemons/{daemon}/shares` | | `admin_daemon_share_set` | Set a daemon's shares | write | `admin:write` | `PUT /api/v1/admin/daemons/{daemon}/shares` | | `admin_daemon_update` | Change a daemon | write | `admin:write` | `PATCH /api/v1/admin/daemons/{daemon}` | | `admin_drill_get` | Read failover drill options | read | `admin:read` | `GET /api/v1/admin/failover-drill` | | `admin_drill_run` | Plan a failover drill | read | `admin:read` | `POST /api/v1/admin/failover-drill` | | `admin_eval_golden_create` | Add a golden task | write | `admin:write` | `POST /api/v1/admin/evals/golden` | | `admin_eval_golden_delete` | Delete a golden task | write (destructive) | `admin:write` | `DELETE /api/v1/admin/evals/golden/{golden}` | | `admin_eval_golden_update` | Change a golden task | write | `admin:write` | `PUT /api/v1/admin/evals/golden/{golden}` | | `admin_eval_list` | List evals | read | `admin:read` | `GET /api/v1/admin/evals` | | `admin_eval_run_cancel` | Cancel an eval run | write | `admin:write` | `POST /api/v1/admin/evals/runs/{run}/cancel` | | `admin_eval_run_create` | Queue an eval run | write | `admin:write` | `POST /api/v1/admin/evals/runs` | | `admin_eval_run_get` | Read an eval run | read | `admin:read` | `GET /api/v1/admin/evals/runs/{run}` | | `admin_eval_runner_delete` | Remove an eval runner | write (destructive) | `admin:write` | `DELETE /api/v1/admin/evals/runners/{runner}` | | `admin_eval_suggestion_dismiss` | Dismiss an eval suggestion | write | `admin:write` | `POST /api/v1/admin/evals/suggestions/{suggestion}/dismiss` | | `admin_experiment_apply` | Make an experiment's gear the default | write | `admin:write` | `POST /api/v1/admin/experiments/{experiment}/apply` | | `admin_experiment_create` | Start a gear experiment | write | `admin:write` | `POST /api/v1/admin/experiments` | | `admin_experiment_delete` | Delete a gear experiment | write (destructive) | `admin:write` | `DELETE /api/v1/admin/experiments/{experiment}` | | `admin_experiment_get` | Read a gear experiment | read | `admin:read` | `GET /api/v1/admin/experiments/{experiment}` | | `admin_experiment_list` | List gear experiments | read | `admin:read` | `GET /api/v1/admin/experiments` | | `admin_experiment_stop` | Stop a gear experiment | write | `admin:write` | `POST /api/v1/admin/experiments/{experiment}/stop` | | `admin_failure_list` | List session failures | read | `admin:read` | `GET /api/v1/admin/failures` | | `admin_failure_run` | Classify failures now | write | `admin:write` | `POST /api/v1/admin/failures/classify` | | `admin_failure_settings_get` | Read failure classifier settings | read | `admin:read` | `GET /api/v1/admin/failures/settings` | | `admin_failure_settings_set` | Set the failure classifier | write | `admin:write` | `PUT /api/v1/admin/failures/settings` | | `admin_filter_list` | List prompt filters | read | `admin:read` | `GET /api/v1/admin/filters` | | `admin_filter_set` | Replace the prompt filters | write | `admin:write` | `PUT /api/v1/admin/filters` | | `admin_filter_test` | Test prompt filters on text | write | `admin:write` | `POST /api/v1/admin/filters/test` | | `admin_gear_list` | List gears | read | `admin:read` | `GET /api/v1/admin/gears` | | `admin_gear_set` | Save gears | write | `admin:write` | `PUT /api/v1/admin/gears` | | `admin_grant_create` | Share daemons with a team | write | `admin:write` | `POST /api/v1/admin/grants` | | `admin_grant_delete` | Revoke a GPU grant | write (destructive) | `admin:write` | `DELETE /api/v1/admin/grants/{grant}` | | `admin_grant_list` | List GPU grants | read | `admin:read` | `GET /api/v1/admin/grants` | | `admin_grant_update` | Change a GPU grant | write | `admin:write` | `PATCH /api/v1/admin/grants/{grant}` | | `admin_guardrail_create` | Add a guardrail | write | `admin:write` | `POST /api/v1/admin/guardrails` | | `admin_guardrail_delete` | Remove a guardrail | write (destructive) | `admin:write` | `DELETE /api/v1/admin/guardrails/{code}` | | `admin_guardrail_draft` | Draft a guardrail from a sentence | write | `admin:write` | `POST /api/v1/admin/guardrails/draft` | | `admin_guardrail_drafting_set` | Set guardrail drafting | write | `admin:write` | `PUT /api/v1/admin/guardrail-drafting` | | `admin_guardrail_list` | List guardrails | read | `admin:read` | `GET /api/v1/admin/guardrails` | | `admin_guardrail_override_set` | Override an org guardrail for a team | write | `admin:write` | `PUT /api/v1/admin/guardrails/overrides` | | `admin_guardrail_shield_set` | Set the injection shield classifier | write | `admin:write` | `PUT /api/v1/admin/injection-classifier` | | `admin_guardrail_suggestion_decide` | Decide a suggested guardrail | write | `admin:write` | `POST /api/v1/admin/guardrails/suggestions/{suggestion}` | | `admin_guardrail_test` | Test guardrails on text | read | `admin:read` | `POST /api/v1/admin/guardrails/test` | | `admin_guardrail_update` | Change a guardrail | write | `admin:write` | `PATCH /api/v1/admin/guardrails/{code}` | | `admin_handoff_delete` | Cancel a handoff | write (destructive) | `admin:write` | `DELETE /api/v1/admin/handoffs/{handoff}` | | `admin_handoff_list` | List session handoffs | read | `admin:read` | `GET /api/v1/admin/handoffs` | | `admin_handoff_respond` | Decline a handoff | write | `admin:write` | `POST /api/v1/admin/handoffs/{handoff}/decline` | | `admin_intake_get` | Read issue intake | read | `admin:read` | `GET /api/v1/admin/intake` | | `admin_intake_job_cancel` | Cancel an intake job | write | `admin:write` | `POST /api/v1/admin/intake/jobs/{job}/cancel` | | `admin_intake_job_retry` | Retry an intake job | write | `admin:write` | `POST /api/v1/admin/intake/jobs/{job}/retry` | | `admin_intake_runner_delete` | Remove an intake runner | write (destructive) | `admin:write` | `DELETE /api/v1/admin/intake/runners/{runner}` | | `admin_integration_channel_delete` | Clear a Slack channel's gear | write (destructive) | `admin:write` | `DELETE /api/v1/admin/integrations/{integration}/channels` | | `admin_integration_channel_set` | Set a Slack channel's gear | write | `admin:write` | `PUT /api/v1/admin/integrations/{integration}/channels` | | `admin_integration_create` | Start an integration | write | `admin:write` | `POST /api/v1/admin/integrations` | | `admin_integration_delete` | Disconnect an integration | write (destructive) | `admin:write` | `DELETE /api/v1/admin/integrations/{integration}` | | `admin_integration_list` | List integrations | read | `admin:read` | `GET /api/v1/admin/integrations` | | `admin_integration_member_unlink` | Unlink a Slack user | write (destructive) | `admin:write` | `DELETE /api/v1/admin/integrations/{integration}/members` | | `admin_integration_test` | Check a Slack integration | write | `admin:write` | `POST /api/v1/admin/integrations/{integration}/check` | | `admin_integration_update` | Change an integration | write | `admin:write` | `PATCH /api/v1/admin/integrations/{integration}` | | `admin_invitation_create` | Invite someone to the org | write | `admin:write` | `POST /api/v1/admin/invitations` | | `admin_invitation_delete` | Revoke an invitation | write (destructive) | `admin:write` | `DELETE /api/v1/admin/invitations/{invitation}` | | `admin_jointoken_delete` | Delete a daemon join token | write (destructive) | `admin:write` | `DELETE /api/v1/admin/join-tokens/{jointoken}` | | `admin_key_delete` | Revoke a Venom API key | write (destructive) | `admin:write` | `DELETE /api/v1/admin/keys/{key_id}` | | `admin_key_list` | List Venom API keys | read | `admin:read` | `GET /api/v1/admin/keys` | | `admin_key_scope_set` | Set a key's scope | write | `admin:write` | `PATCH /api/v1/admin/keys/{key_id}/scope` | | `admin_key_update` | Pause or resume a Venom API key | write | `admin:write` | `PATCH /api/v1/admin/keys/{key_id}` | | `admin_keyrotation_get` | Read the key rotation policy | read | `admin:read` | `GET /api/v1/admin/key-rotation` | | `admin_keyrotation_set` | Set the key rotation policy | write | `admin:write` | `PUT /api/v1/admin/key-rotation` | | `admin_knowledge_ask` | Ask the organisation's knowledge | write | `admin:write` | `POST /api/v1/admin/knowledge/ask` | | `admin_library_create` | Add a library item | write | `admin:write` | `POST /api/v1/admin/library` | | `admin_library_delete` | Delete a library item | write (destructive) | `admin:write` | `DELETE /api/v1/admin/library/{item}` | | `admin_library_get` | Read a library item | read | `admin:read` | `GET /api/v1/admin/library/{item}` | | `admin_library_list` | List the library | read | `admin:read` | `GET /api/v1/admin/library` | | `admin_library_publish` | Publish a library draft | write | `admin:write` | `POST /api/v1/admin/library/{item}/publish` | | `admin_library_rollback` | Roll a library item back | write | `admin:write` | `POST /api/v1/admin/library/{item}/rollback` | | `admin_library_test` | Test a library change | write | `admin:write` | `POST /api/v1/admin/library/{item}/test` | | `admin_library_update` | Change a library item | write | `admin:write` | `PATCH /api/v1/admin/library/{item}` | | `admin_library_version_get` | Read a library version | read | `admin:read` | `GET /api/v1/admin/library/{item}/version` | | `admin_lifecycle_apply` | Switch gears off a retiring model | write | `admin:write` | `POST /api/v1/admin/lifecycle/switch` | | `admin_lifecycle_get` | Read model lifecycle | read | `admin:read` | `GET /api/v1/admin/lifecycle` | | `admin_lifecycle_set` | Set lifecycle warnings | write | `admin:write` | `PUT /api/v1/admin/lifecycle/settings` | | `admin_live_list` | List live sessions | read | `admin:read` | `GET /api/v1/admin/live-sessions` | | `admin_live_stop` | Stop a live session | write (destructive) | `admin:write` | `DELETE /api/v1/admin/live-sessions/{session}` | | `admin_live_update` | Change who can use a live session | write | `admin:write` | `PATCH /api/v1/admin/live-sessions/{session}` | | `admin_logging_get` | Read request logging settings | read | `admin:read` | `GET /api/v1/admin/logging` | | `admin_logging_set` | Set request logging | write | `admin:write` | `PUT /api/v1/admin/logging` | | `admin_machine_delete` | Terminate an autoscaled machine | write (destructive) | `admin:write` | `DELETE /api/v1/admin/autoscale/machines/{machine}` | | `admin_machine_stop` | Drain an autoscaled machine | write | `admin:write` | `POST /api/v1/admin/autoscale/machines/{machine}/drain` | | `admin_mcp_catalog_list` | List the MCP server catalog | read | `admin:read` | `GET /api/v1/admin/mcp-catalog` | | `admin_mcpserver_create` | Add an MCP server by URL | write | `admin:write` | `POST /api/v1/admin/mcp-servers` | | `admin_mcpserver_delete` | Remove one of the org's MCP servers | write (destructive) | `admin:write` | `DELETE /api/v1/admin/mcp-servers/{server}` | | `admin_mcpserver_get` | Read one of the org's MCP servers | read | `admin:read` | `GET /api/v1/admin/mcp-servers/{server}` | | `admin_mcpserver_list` | List the org's own MCP servers | read | `admin:read` | `GET /api/v1/admin/mcp-servers` | | `admin_mcpserver_test` | Test an MCP server's connection | write | `admin:write` | `POST /api/v1/admin/mcp-servers/test` | | `admin_mcpserver_update` | Change one of the org's MCP servers | write | `admin:write` | `PATCH /api/v1/admin/mcp-servers/{server}` | | `admin_member_list` | List organisation members | read | `admin:read` | `GET /api/v1/admin/members` | | `admin_member_remove` | Remove a member | write (destructive) | `admin:write` | `DELETE /api/v1/admin/members/{member}` | | `admin_member_update` | Change a member's role | write | `admin:write` | `PATCH /api/v1/admin/members/{member}` | | `admin_memory_approve` | Approve a proposed memory | write | `admin:write` | `POST /api/v1/admin/memory/{memory}/approve` | | `admin_memory_confirm` | Confirm a memory is still true | write | `admin:write` | `POST /api/v1/admin/memory/{memory}/confirm` | | `admin_memory_create` | Add a memory | write | `admin:write` | `POST /api/v1/admin/memory` | | `admin_memory_delete` | Delete a memory | write (destructive) | `admin:write` | `DELETE /api/v1/admin/memory/{memory}` | | `admin_memory_list` | List shared memory | read | `admin:read` | `GET /api/v1/admin/memory` | | `admin_memory_reject` | Reject a proposed memory | write | `admin:write` | `POST /api/v1/admin/memory/{memory}/reject` | | `admin_memory_update` | Edit a memory | write | `admin:write` | `PATCH /api/v1/admin/memory/{memory}` | | `admin_modelaccess_get` | Read model access by role | read | `admin:read` | `GET /api/v1/admin/model-access` | | `admin_modelaccess_set` | Set model access by role | write | `admin:write` | `PUT /api/v1/admin/model-access` | | `admin_myguardrail_create` | Add my guardrail | write | `admin:write` | `POST /api/v1/admin/me/guardrails` | | `admin_myguardrail_delete` | Remove my guardrail | write (destructive) | `admin:write` | `DELETE /api/v1/admin/me/guardrails/{code}` | | `admin_myguardrail_draft` | Draft a personal guardrail | write | `admin:write` | `POST /api/v1/admin/me/guardrails/draft` | | `admin_myguardrail_list` | List my guardrails | read | `admin:read` | `GET /api/v1/admin/me/guardrails` | | `admin_myguardrail_request` | Suggest a guardrail to a team | write | `admin:write` | `POST /api/v1/admin/me/guardrails/{code}/suggest` | | `admin_myguardrail_set` | Switch a guardrail for me | write | `admin:write` | `PUT /api/v1/admin/me/guardrails/overrides` | | `admin_myguardrail_test` | Test my guardrails on text | read | `admin:read` | `POST /api/v1/admin/me/guardrails/test` | | `admin_myguardrail_update` | Change my guardrail | write | `admin:write` | `PATCH /api/v1/admin/me/guardrails/{code}` | | `admin_onboarding_create` | Create an onboarding path | write | `admin:write` | `POST /api/v1/admin/onboarding` | | `admin_onboarding_delete` | Delete an onboarding path | write (destructive) | `admin:write` | `DELETE /api/v1/admin/onboarding/{path}` | | `admin_onboarding_list` | List onboarding paths | read | `admin:read` | `GET /api/v1/admin/onboarding` | | `admin_onboarding_mark` | Mark an onboarding step | write | `admin:write` | `POST /api/v1/admin/onboarding/{path}/steps` | | `admin_onboarding_update` | Change an onboarding path | write | `admin:write` | `PATCH /api/v1/admin/onboarding/{path}` | | `admin_org_update` | Rename the organisation | write | `admin:write` | `PATCH /api/v1/admin/org` | | `admin_outcomes_set` | Set session outcome tracking | write | `admin:write` | `PUT /api/v1/admin/session-outcomes` | | `admin_pack_apply` | Install a starter pack | write | `admin:write` | `POST /api/v1/admin/packs/{pack}` | | `admin_pack_get` | Read a starter pack | read | `admin:read` | `GET /api/v1/admin/packs/{pack}` | | `admin_pack_list` | List starter packs | read | `admin:read` | `GET /api/v1/admin/packs` | | `admin_pack_remove` | Uninstall a starter pack | write (destructive) | `admin:write` | `DELETE /api/v1/admin/packs/{pack}` | | `admin_pause_list` | List paused sessions | read | `admin:read` | `GET /api/v1/admin/session-pauses` | | `admin_pause_update` | Resume a paused session | write | `admin:write` | `POST /api/v1/admin/session-pauses/{pause}/resume` | | `admin_platform_keys_set` | Use Venom's keys after yours | write | `admin:write` | `PUT /api/v1/admin/platform-keys` | | `admin_pool_delete` | Delete an autoscaling pool | write (destructive) | `admin:write` | `DELETE /api/v1/admin/autoscale/pools/{pool}` | | `admin_prewarm_delete` | Remove the prewarm schedule | write (destructive) | `admin:write` | `DELETE /api/v1/admin/prewarm` | | `admin_prewarm_get` | Read the prewarm schedule | read | `admin:read` | `GET /api/v1/admin/prewarm` | | `admin_prewarm_run` | Prewarm now | write | `admin:write` | `POST /api/v1/admin/prewarm/run` | | `admin_prewarm_set` | Save the prewarm schedule | write | `admin:write` | `PUT /api/v1/admin/prewarm` | | `admin_prompttest_apply` | Publish a prompt test's winner | write | `admin:write` | `POST /api/v1/admin/prompt-tests/{test}/apply` | | `admin_prompttest_create` | Start a prompt test | write | `admin:write` | `POST /api/v1/admin/prompt-tests` | | `admin_prompttest_delete` | Delete a prompt test | write (destructive) | `admin:write` | `DELETE /api/v1/admin/prompt-tests/{test}` | | `admin_prompttest_get` | Read a prompt test | read | `admin:read` | `GET /api/v1/admin/prompt-tests/{test}` | | `admin_prompttest_list` | List prompt tests | read | `admin:read` | `GET /api/v1/admin/prompt-tests` | | `admin_prompttest_stop` | Stop a prompt test | write | `admin:write` | `POST /api/v1/admin/prompt-tests/{test}/stop` | | `admin_provider_add` | Add a provider key | write | `admin:write` | `POST /api/v1/admin/providers` | | `admin_provider_delete` | Delete a provider key | write (destructive) | `admin:write` | `DELETE /api/v1/admin/providers/{key_id}` | | `admin_provider_list` | List provider keys | read | `admin:read` | `GET /api/v1/admin/providers` | | `admin_provider_reorder` | Order a provider's keys | write | `admin:write` | `POST /api/v1/admin/providers/reorder` | | `admin_provider_rotate` | Rotate a provider key | write | `admin:write` | `POST /api/v1/admin/providers/{key_id}/rotate` | | `admin_provider_rotation_set` | Finish or roll back a key rotation | write | `admin:write` | `POST /api/v1/admin/providers/{key_id}/rotation` | | `admin_provider_test` | Check a stored provider key | write | `admin:write` | `POST /api/v1/admin/providers/{key_id}/test` | | `admin_provider_update` | Change a provider key | write | `admin:write` | `PATCH /api/v1/admin/providers/{key_id}` | | `admin_quality_get` | Read quality checks | read | `admin:read` | `GET /api/v1/admin/quality` | | `admin_quality_set` | Set quality checks | write | `admin:write` | `PUT /api/v1/admin/quality` | | `admin_quality_suite_create` | Create a quality suite | write | `admin:write` | `POST /api/v1/admin/quality/suites` | | `admin_quality_suite_delete` | Delete a quality suite | write (destructive) | `admin:write` | `DELETE /api/v1/admin/quality/suites/{suite}` | | `admin_quality_suite_update` | Change a quality suite | write | `admin:write` | `PATCH /api/v1/admin/quality/suites/{suite}` | | `admin_quality_test` | Test one quality case | write | `admin:write` | `POST /api/v1/admin/quality/test` | | `admin_redteam_get` | Read red team results | read | `admin:read` | `GET /api/v1/admin/redteam` | | `admin_redteam_run` | Run the red team corpus | write | `admin:write` | `POST /api/v1/admin/redteam/runs` | | `admin_redteam_run_get` | Read a red team run | read | `admin:read` | `GET /api/v1/admin/redteam/runs/{run}` | | `admin_request_get` | Read a request's trace | read | `admin:read` | `GET /api/v1/admin/requests/{request}` | | `admin_routing_delete` | Remove a routing policy | write (destructive) | `admin:write` | `DELETE /api/v1/admin/routing` | | `admin_routing_get` | Read the routing policy | read | `admin:read` | `GET /api/v1/admin/routing` | | `admin_routing_preview` | Preview how a model routes | read | `admin:read` | `GET /api/v1/admin/routing/preview` | | `admin_routing_set` | Set a routing policy | write | `admin:write` | `PUT /api/v1/admin/routing` | | `admin_routing_trusted_add` | Trust a public node | write | `admin:write` | `POST /api/v1/admin/routing/trusted` | | `admin_routing_trusted_remove` | Stop trusting a public node | write (destructive) | `admin:write` | `DELETE /api/v1/admin/routing/trusted/{daemon_id}` | | `admin_savings_apply` | Apply a savings tier | write | `admin:write` | `POST /api/v1/admin/savings/apply` | | `admin_savings_commitments_set` | Set commitment prices | write | `admin:write` | `PUT /api/v1/admin/savings/commitments` | | `admin_savings_get` | Read savings suggestions | read | `admin:read` | `GET /api/v1/admin/savings` | | `admin_scanner_get` | Read the secret scanner | read | `admin:read` | `GET /api/v1/admin/secret-scanner` | | `admin_scanner_set` | Set the secret scanner | write | `admin:write` | `PUT /api/v1/admin/secret-scanner` | | `admin_scorecard_get` | Read the scorecard | read | `admin:read` | `GET /api/v1/admin/scorecard` | | `admin_search_get` | Read the search settings | read | `admin:read` | `GET /api/v1/admin/search` | | `admin_search_set` | Change the search settings | write | `admin:write` | `PUT /api/v1/admin/search` | | `admin_session_summaries_get` | Read session summary settings | read | `admin:read` | `GET /api/v1/admin/session-summaries` | | `admin_session_summaries_set` | Set session summary settings | write | `admin:write` | `PUT /api/v1/admin/session-summaries` | | `admin_sessionguard_get` | Read session guard limits | read | `admin:read` | `GET /api/v1/admin/session-guard` | | `admin_sessionguard_set` | Set session guard limits | write | `admin:write` | `PUT /api/v1/admin/session-guard` | | `admin_shadow_get` | Read shadow routing | read | `admin:read` | `GET /api/v1/admin/shadow` | | `admin_shadow_set` | Set shadow routing | write | `admin:write` | `PUT /api/v1/admin/shadow` | | `admin_shadowtest_apply` | Switch gears to a shadow test's candidate | write | `admin:write` | `POST /api/v1/admin/shadow/tests/{test}/apply` | | `admin_shadowtest_create` | Start a shadow test | write | `admin:write` | `POST /api/v1/admin/shadow/tests` | | `admin_shadowtest_delete` | Delete a shadow test | write (destructive) | `admin:write` | `DELETE /api/v1/admin/shadow/tests/{test}` | | `admin_shadowtest_get` | Read a shadow test | read | `admin:read` | `GET /api/v1/admin/shadow/tests/{test}` | | `admin_shadowtest_revert` | Revert a shadow test's switch | write | `admin:write` | `POST /api/v1/admin/shadow/tests/{test}/revert` | | `admin_shadowtest_update` | Change a shadow test | write | `admin:write` | `PATCH /api/v1/admin/shadow/tests/{test}` | | `admin_share_comment_create` | Comment on a shared session | write | `admin:write` | `POST /api/v1/admin/shares/{share}/comments` | | `admin_share_comment_delete` | Delete a share comment | write (destructive) | `admin:write` | `DELETE /api/v1/admin/shares/{share}/comments` | | `admin_share_delete` | Delete a shared session | write (destructive) | `admin:write` | `DELETE /api/v1/admin/shares/{share}` | | `admin_share_link_delete` | Revoke a shared session's public link | write (destructive) | `admin:write` | `DELETE /api/v1/admin/shares/{share}/public-link` | | `admin_share_list` | List shared sessions | read | `admin:read` | `GET /api/v1/admin/shares` | | `admin_share_update` | Change a shared session | write | `admin:write` | `PATCH /api/v1/admin/shares/{share}` | | `admin_sharing_get` | Read session sharing settings | read | `admin:read` | `GET /api/v1/admin/session-sharing` | | `admin_sharing_set` | Set session sharing settings | write | `admin:write` | `PUT /api/v1/admin/session-sharing` | | `admin_skill_approve` | Approve a skill's pending update | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/approve` | | `admin_skill_bulk_delete` | Delete several skills | write (destructive) | `admin:write` | `POST /api/v1/admin/skills/bulk/delete` | | `admin_skill_bulk_update` | Change several skills | write | `admin:write` | `POST /api/v1/admin/skills/bulk` | | `admin_skill_create` | Add a skill from text | write | `admin:write` | `POST /api/v1/admin/skills` | | `admin_skill_delete` | Delete a skill | write (destructive) | `admin:write` | `DELETE /api/v1/admin/skills/{skill}` | | `admin_skill_disable` | Turn a skill off | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/disable` | | `admin_skill_export` | Download skills as a zip | read | `admin:read` | `POST /api/v1/admin/skills/export` | | `admin_skill_get` | Read a skill | read | `admin:read` | `GET /api/v1/admin/skills/{skill}` | | `admin_skill_import` | Import a skill from a URL | write | `admin:write` | `POST /api/v1/admin/skills/import` | | `admin_skill_list` | List the org's skills | read | `admin:read` | `GET /api/v1/admin/skills` | | `admin_skill_publish` | Turn a skill on | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/publish` | | `admin_skill_refresh` | Check a skill's source for updates | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/check` | | `admin_skill_reject` | Reject a skill's pending update | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/reject` | | `admin_skill_rollback` | Roll a skill back | write | `admin:write` | `POST /api/v1/admin/skills/{skill}/rollback` | | `admin_skill_scope_set` | Set who gets a skill | write | `admin:write` | `PUT /api/v1/admin/skills/{skill}/scope` | | `admin_skill_source_import` | Import several skills from a URL | write | `admin:write` | `POST /api/v1/admin/skills/source/import` | | `admin_skill_source_preview` | See the skills a URL holds | write | `admin:write` | `POST /api/v1/admin/skills/source` | | `admin_skill_update` | Change a skill | write | `admin:write` | `PATCH /api/v1/admin/skills/{skill}` | | `admin_skill_version_get` | Read a skill version | read | `admin:read` | `GET /api/v1/admin/skills/{skill}/version` | | `admin_spendalert_list` | List spend alerts | read | `admin:read` | `GET /api/v1/admin/spend-alerts` | | `admin_spendalert_set` | Set spend alert settings | write | `admin:write` | `PUT /api/v1/admin/spend-alerts` | | `admin_spendcap_get` | Read the org spend cap | read | `admin:read` | `GET /api/v1/admin/spend-cap` | | `admin_spendcap_set` | Set the org spend cap | write | `admin:write` | `PUT /api/v1/admin/spend-cap` | | `admin_spendlimit_list` | List every AI limit and today's spend | read | `admin:read` | `GET /api/v1/admin/spend/limits` | | `admin_spendlimit_set` | Change one AI limit | write | `admin:write` | `PUT /api/v1/admin/spend/limits/{limit}` | | `admin_sso_domain_add` | Add an SSO domain | write | `admin:write` | `POST /api/v1/admin/sso/domains` | | `admin_sso_domain_delete` | Remove an SSO domain | write (destructive) | `admin:write` | `DELETE /api/v1/admin/sso/domains/{domain_id}` | | `admin_sso_domain_validate` | Verify an SSO domain | write | `admin:write` | `POST /api/v1/admin/sso/domains/{domain_id}/validate` | | `admin_sso_get` | Read single sign-on | read | `admin:read` | `GET /api/v1/admin/sso` | | `admin_sso_group_list` | List SCIM groups | read | `admin:read` | `GET /api/v1/admin/sso/groups` | | `admin_sso_group_team_set` | Sync a SCIM group into a team | write | `admin:write` | `PUT /api/v1/admin/sso/groups/{group_id}/team` | | `admin_sso_provisioning_set` | Set SSO provisioning | write | `admin:write` | `PUT /api/v1/admin/sso/provisioning` | | `admin_sso_token_delete` | Revoke a SCIM token | write (destructive) | `admin:write` | `DELETE /api/v1/admin/sso/tokens/{token_id}` | | `admin_team_list` | List teams | read | `admin:read` | `GET /api/v1/admin/teams` | | `admin_team_permissions_get` | Read a team's permission profile | read | `admin:read` | `GET /api/v1/admin/teams/{team}/permissions` | | `admin_team_permissions_set` | Set a team's permission profile | write | `admin:write` | `PUT /api/v1/admin/teams/{team}/permissions` | | `admin_webhook_delete` | Delete an event webhook | write (destructive) | `admin:write` | `DELETE /api/v1/admin/webhooks/{endpoint}` | | `admin_webhook_delivery_list` | List webhook deliveries | read | `admin:read` | `GET /api/v1/admin/webhook-deliveries` | | `admin_webhook_delivery_retry` | Retry a webhook delivery | write | `admin:write` | `POST /api/v1/admin/webhook-deliveries/{delivery}/retry` | | `admin_webhook_list` | List event webhooks | read | `admin:read` | `GET /api/v1/admin/webhooks` | | `admin_webhook_test` | Send a test event | write | `admin:write` | `POST /api/v1/admin/webhooks/{endpoint}/test` | | `admin_webhook_update` | Change an event webhook | write | `admin:write` | `PATCH /api/v1/admin/webhooks/{endpoint}` | `admin_team_list` lists key groups, the mesh's groups of API keys, join tokens and daemons. The org's teams of people are the `org_team_*` tools ([Build on Org and teams](/docs/developers/org.md)). ## Other admin and mesh APIs {#other-apis} These APIs are not MCP servers. Each has its own credential and its own reference: | API | Prefix | Credential | Reference | |---|---|---|---| | Admin API | `/api/admin/v1/*` | a key group admin key (`vak_…`, made only with the cloud admin token) or the deployment's cloud admin token. A personal key does not open it | [Venom Cloud APIs overview](/docs/cloud/api-overview.md), [Admin API: access](/docs/cloud/api-admin-access.md), [routing](/docs/cloud/api-admin-routing.md), [spend](/docs/cloud/api-admin-spend.md), [fleet](/docs/cloud/api-admin-fleet.md), [logs and audit](/docs/cloud/api-admin-observability.md) | | Client API | `/v1/*` | a client key (`vck_…`), scoped to one key group's models, limits and budgets | [Inference API](/docs/cloud/api-inference.md) and the generated reference at `/docs/api/cloud` | | Daemon API | `/api/mesh/v1/*` | a join token (`vjt_…`) once, to enrol; then `Authorization: VenomMesh `, a short-lived JWT the daemon signs with its own key | [Daemon API](/docs/mesh/daemon-api.md) | | SCIM | `/scim/v2/*` | a SCIM token (`vsc_…`) an owner makes | [SCIM API](/docs/cloud/api-scim.md) | Use the `admin_*` tools when an agent acts for a member. Use the admin API for automation that runs as a key group's admin or as the operator of a self-hosted deployment. ## Related {#related} - [Venom Cloud APIs overview](/docs/cloud/api-overview.md): every surface, credential, error shape and rate limit. - [Members and roles](/docs/cloud/console-orgs-members.md): what each org role may do. - [Build on Org and teams](/docs/developers/org.md): teams of people, shared by every product. - [Authentication and scopes](/docs/developers/auth.md), [Errors, limits and pagination](/docs/developers/conventions.md), [Webhooks and events](/docs/developers/webhooks.md), [MCP](/docs/developers/mcp.md) and [REST](/docs/developers/rest.md). ================================================================================ # Build on Studio URL: https://cloud.usevenom.dev/docs/developers/studio Description: Make decks, pages and HTML pages from code or an agent. Create them from blocks and charts, change one slide or block by id, keep versions, and share by link over MCP and REST. An artifact is data: a deck is a list of slides, a page is a list of blocks, and Venom draws them with the organisation's theme. Your code or agent sends compact specs and small edits instead of HTML. See [Studio](/docs/studio.md) for the product and [Blocks and charts](/docs/studio/blocks.md) for the component library. ## What you can build {#build} - **A report generator.** Create a page with a heading, a `stats` row and a few charts from your own data, then hand the user the `url`. - **A deck an agent iterates on.** Create the outline once, then change a slide at a time with `studio_content_edit`. Each call is a few lines, and each write is a version the user can go back to. - **A public one-pager.** Create a page, then `studio_share_create` for a link anyone can open, and `studio_share_revoke` when it has done its job. - **An HTML dashboard.** For what blocks cannot say, an `html` artifact: your own markup, shown sandboxed with no network. ## At a glance {#glance} Generated from the code on every docs build. | | | |---|---| | MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/studio`, server name `venom-studio` | | Connect | `claude mcp add --transport http venom-studio https://cloud.usevenom.dev/workspace/mcp/studio` | | MCP tools | 30 (15 read, 15 write) | | OAuth scopes | `studio:read` `studio:write` | | REST twin | 31 routes under `https://cloud.usevenom.dev/api/v1` | | Webhook events | none yet | ## Authentication and scopes {#scopes} - A **personal API key or an OAuth grant** acts as the member, with their org role's rights. OAuth apps need `studio:read` for the read tools and `studio:write` for the rest. - A **team key bound to a service agent**, or a key naming an agent with `x-venom-agent`, acts as that agent and owns what it makes. - A **team key with no agent** only reads what the organisation shares. Artifacts are private until their owner sets visibility to a team or the org, or creates a public link. An artifact the caller may not see is "No such artifact", the same as a missing one. ## Worked example {#example} Create a one-slide deck and then change its title by id. `$VENOM_KEY` is a personal key. ```bash curl -X POST "$VENOM_CLOUD/api/v1/studio/artifacts" \ -H "Authorization: Bearer $VENOM_KEY" -H 'Content-Type: application/json' -H 'Idempotency-Key: q3-review-1' \ -d '{"kind": "deck", "title": "Q3 review", "content": {"slides": [ {"id": "intro", "layout": "title", "content": {"title": "Q3 review", "subtitle": "Growth and margin"}}]}}' ``` The answer has the artifact's `id`, `url`, `version` and the `ids` it made. Then: ```bash curl -X POST "$VENOM_CLOUD/api/v1/studio/artifacts/$ID/edit" \ -H "Authorization: Bearer $VENOM_KEY" -H 'Content-Type: application/json' -H 'If-Match: "1"' \ -d '{"ops": [{"op": "slide.patch", "id": "intro", "content": {"subtitle": "Growth, margin, next steps"}}]}' ``` A stale `If-Match` is a `412 version_conflict` with the current version in the message. A bad spec is a `422` whose message lists every problem with its path and the allowed values. ## REST routes {#rest} The REST twin: 31 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)). | Method | Path | Summary | MCP tool | |---|---|---|---| | GET | `/api/v1/studio/catalog` | The block types and slide layouts | `studio_catalog_get` | | GET | `/api/v1/studio/components` | The schema and an example of block types | `studio_component_get` | | GET | `/api/v1/studio/layouts` | The slide layouts | `studio_layout_get` | | GET | `/api/v1/studio/themes` | The built-in and the org's themes, or one in full | `studio_theme_list` | | PUT | `/api/v1/studio/themes/{id}` | Create, change or delete an org theme, or make it the default | `studio_theme_set` | | POST | `/api/v1/studio/theme-import` | Propose a theme from a design system's files, or save it | `studio_theme_import` | | GET | `/api/v1/studio/marks` | The organisation's default marks | `studio_marks_get` | | PUT | `/api/v1/studio/marks` | Set the organisation's default marks (header, footer, company, logo, author, date, label, numbers) | `studio_marks_set` | | GET | `/api/v1/studio/artifacts` | List decks, pages and html pages | `studio_artifact_list` | | POST | `/api/v1/studio/artifacts` | Create a deck, a page or an html page | `studio_artifact_create` | | GET | `/api/v1/studio/artifacts/search` | Search artifacts by title and text | `studio_artifact_search` | | POST | `/api/v1/studio/artifacts/validate` | Dry-run content, html or ops without saving | `studio_artifact_validate` | | GET | `/api/v1/studio/artifacts/{id}` | Read an artifact (meta, outline or content) | `studio_artifact_get` | | PATCH | `/api/v1/studio/artifacts/{id}` | Change title, theme, tweaks, marks or sharing | `studio_artifact_update` | | POST | `/api/v1/studio/artifacts/{id}/delete` | Move an artifact to the trash | `studio_artifact_delete` | | POST | `/api/v1/studio/artifacts/{id}/restore` | Bring a deleted artifact back | `studio_artifact_restore` | | POST | `/api/v1/studio/artifacts/{id}/duplicate` | Copy an artifact | `studio_artifact_duplicate` | | GET | `/api/v1/studio/artifacts/{id}/outline` | Ids and titles of an artifact's slides or blocks | `studio_outline_get` | | POST | `/api/v1/studio/artifacts/{id}/edit` | Edit slides or blocks by id (a batch of ops), or replace the content | `studio_content_edit` | | POST | `/api/v1/studio/artifacts/{id}/html` | Edit an html page with anchored string edits | `studio_html_edit` | | GET | `/api/v1/studio/artifacts/{id}/export` | Export as json, markdown, outline, html, pptx or print (the print view and its document) | `studio_artifact_export` | | GET | `/api/v1/studio/artifacts/{id}/preview` | Preview links and a text summary | `studio_preview_get` | | GET | `/api/v1/studio/artifacts/{id}/versions` | An artifact's versions | `studio_version_list` | | POST | `/api/v1/studio/artifacts/{id}/versions/{version}/restore` | Make an earlier version current | `studio_version_restore` | | GET | `/api/v1/studio/artifacts/{id}/shares` | An artifact's public links | `studio_share_list` | | POST | `/api/v1/studio/artifacts/{id}/shares` | Create a public link | `studio_share_create` | | POST | `/api/v1/studio/artifacts/{id}/shares/revoke` | Revoke one public link or all | `studio_share_revoke` | | GET | `/api/v1/studio/research` | Your recent research runs | `studio_research_get` | | POST | `/api/v1/studio/research` | Start a research run: plan, research, analysis, build and review of a researched report | `studio_research_start` | | GET | `/api/v1/studio/research/{id}` | A research run's plan card: goals, steps, researchers, sources, the artifact | `studio_research_get` | | POST | `/api/v1/studio/research/{id}/cancel` | Cancel a research run | `studio_research_cancel` | ## MCP tools {#tools} 30 tools: 15 read, 15 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP. | Tool | Title | Access | Scope | REST route | |---|---|---|---|---| | `studio_artifact_create` | Create an artifact | write | `studio:write` | `POST /api/v1/studio/artifacts` | | `studio_artifact_delete` | Delete an artifact | write (destructive) | `studio:write` | `POST /api/v1/studio/artifacts/{id}/delete` | | `studio_artifact_duplicate` | Duplicate an artifact | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/duplicate` | | `studio_artifact_export` | Export an artifact | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}/export` | | `studio_artifact_get` | Read an artifact | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}` | | `studio_artifact_list` | List artifacts | read | `studio:read` | `GET /api/v1/studio/artifacts` | | `studio_artifact_restore` | Restore a deleted artifact | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/restore` | | `studio_artifact_search` | Search artifacts | read | `studio:read` | `GET /api/v1/studio/artifacts/search` | | `studio_artifact_update` | Rename, retheme, tweak, mark or share | write | `studio:write` | `PATCH /api/v1/studio/artifacts/{id}` | | `studio_artifact_validate` | Dry-run a spec | read | `studio:read` | `POST /api/v1/studio/artifacts/validate` | | `studio_catalog_get` | List the component library | read | `studio:read` | `GET /api/v1/studio/catalog` | | `studio_component_get` | Get a block's spec | read | `studio:read` | `GET /api/v1/studio/components` | | `studio_content_edit` | Edit slides or blocks by id | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/edit` | | `studio_html_edit` | Edit an html page | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/html` | | `studio_layout_get` | List slide layouts | read | `studio:read` | `GET /api/v1/studio/layouts` | | `studio_marks_get` | Read the org's default marks | read | `studio:read` | `GET /api/v1/studio/marks` | | `studio_marks_set` | Set the org's default marks | write | `studio:write` | `PUT /api/v1/studio/marks` | | `studio_outline_get` | Read an outline (cheap) | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}/outline` | | `studio_preview_get` | Preview links and a text summary | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}/preview` | | `studio_research_cancel` | Cancel a research run | write (destructive) | `studio:write` | `POST /api/v1/studio/research/{id}/cancel` | | `studio_research_get` | Read a research run | read | `studio:read` | `GET /api/v1/studio/research` (+1) | | `studio_research_start` | Start a research run | write | `studio:write` | `POST /api/v1/studio/research` | | `studio_share_create` | Create a public link | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/shares` | | `studio_share_list` | List public links | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}/shares` | | `studio_share_revoke` | Revoke a public link | write (destructive) | `studio:write` | `POST /api/v1/studio/artifacts/{id}/shares/revoke` | | `studio_theme_import` | Propose a theme from a design system | write | `studio:write` | `POST /api/v1/studio/theme-import` | | `studio_theme_list` | List themes | read | `studio:read` | `GET /api/v1/studio/themes` | | `studio_theme_set` | Create, change or delete a theme | write | `studio:write` | `PUT /api/v1/studio/themes/{id}` | | `studio_version_list` | List versions | read | `studio:read` | `GET /api/v1/studio/artifacts/{id}/versions` | | `studio_version_restore` | Restore a version | write | `studio:write` | `POST /api/v1/studio/artifacts/{id}/versions/{version}/restore` | ## Related {#related} - [Studio](/docs/studio.md), [Edit by id](/docs/studio/edits.md) and [Studio for agents](/docs/studio/agents.md). - [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md). ================================================================================ # The venom CLI URL: https://cloud.usevenom.dev/docs/cli Description: How the venom command is organised, the ways to run it (terminal UI, print mode, JSON, RPC) and where each part of it is documented. `venom` is a coding agent for the terminal. It is a distribution of [pi](https://github.com/earendil-works/pi): it starts pi's own command line with venom's extensions loaded (the permission engine, subagents, plan mode, the HUD and the rest) and sovereign defaults (no telemetry, no update checks, no calls to anything but the endpoint you configure). Everything pi's CLI accepts works, and venom adds its own subcommands, flags, slash commands and keys on top. New to venom? Install it and run a first session with the [CLI quickstart](/docs/getting-started/cli-quickstart.md). ## Ways to run it {#run} ```bash venom # the terminal UI in this directory venom "fix the failing test in api/" # the terminal UI, starting with a prompt venom -p "explain this repo" # print mode: one answer on stdout, then exit venom --mode json "list the TODOs" # JSON lines: every event, then exit venom --mode rpc # JSON commands on stdin, events on stdout, until shutdown venom -c # continue the newest session of this directory venom doctor # check the setup ``` With a terminal on stdin and stdout, `venom` opens the terminal UI. When either is redirected and no `--mode` is given, it runs in print mode. [Print, JSON and RPC modes](/docs/cli/headless.md) covers scripting and CI. ## Where things are {#map} | Page | What it covers | |---|---| | [Flags](/docs/cli/flags.md) | every flag `venom` takes: venom's own (permission modes, worktrees, browser, budgets) and pi's (models, sessions, tools, resources) | | [Slash commands](/docs/cli/slash-commands.md) | every `/command` in a session, venom's and pi's | | [Keys](/docs/cli/keys.md) | the leader key (`ctrl+g`), its bindings and the other shortcuts | | [The terminal UI](/docs/cli/tui.md) | the HUD, the call meter, transcript verbosity, reading width, the agents panel, the pull requests pane, sounds and themes | | [Plan mode](/docs/cli/plan-mode.md) | read-only planning, the plan file and approving it | | [Print, JSON and RPC modes](/docs/cli/headless.md) | headless runs, piped stdin, slash commands without a UI, `--json` on subcommands | The subcommands that work outside a session are listed [below](#subcommands). `venom --help` prints venom's commands, flags and environment variables first, then pi's help; `venom --help` prints one command's usage. ## Every subcommand {#subcommands} | Command | What it does | Documented in | |---|---|---| | `venom doctor`, `venom cost`, `venom usage`, `venom explain-cost`, `venom diet`, `venom stats`, `venom forecast`, `venom routes`, `venom flaky`, `venom models` | setup checks, spend, routing, waste, flaky tests, local models | [Cost, health and routing commands](/docs/cli/insight-commands.md) | | `venom init`, `venom explain`, `venom tour`, `venom ask`, `venom onboard`, `venom memory`, `venom index`, `venom lessons` | project setup, memory, onboarding | [Project setup, memory and onboarding commands](/docs/cli/project-commands.md) | | `venom bisect`, `venom try`, `venom intent`, `venom provenance`, `venom revert`, `venom evidence`, `venom ship`, `venom stack`, `venom capture` | git, review and shipping | [Git, review and shipping commands](/docs/cli/git-commands.md) | | `venom -c`, `venom resume`, `venom sessions`, `venom session`, `venom export`, `venom export-traces`, `venom attach`, `venom triage` | sessions | [Sessions, resume and export](/docs/cli/sessions.md) | | `venom workspace` | git worktrees venom made | [Workspaces](/docs/cli/workspaces.md) | | `venom test-impact` | the tests a change can affect | [The agent's tools](/docs/cli/tools.md#test-impact) | | `venom theme`, `venom sounds` | colour themes, event sounds | [The terminal UI](/docs/cli/tui.md) | | `venom config`, `venom gear` | the configuration and gears | [Configuration](/docs/configuration.md) | | `venom trust`, `venom policy`, `venom audit`, `venom egress`, `venom secrets`, `venom actions`, `venom compliance`, `venom redteam`, `venom risk` | trust, policy, audit and risk scoring | [Security](/docs/security.md) | | `venom do`, `venom inbox`, `venom digest`, `venom schedule`, `venom workflow`, `venom spec`, `venom replay`, `venom handoff`, `venom board`, `venom fleet`, `venom intake` | background agents and automation (`venom resume` is also there) | the [automation section](/docs/automation.md) | | `venom review` | a read-only review of a diff, a GitHub pull request or a GitLab merge request | the [automation section](/docs/automation.md) | | `venom plugin`, `venom mcp`, `venom library`, `venom role`, `venom skills`, `venom new`, `venom template` | plugins, MCP servers, the team library, roles, skills, templates | the [plugins section](/docs/plugins.md) | | `venom cloud` | Venom Cloud sign-in | the [cloud section](/docs/cloud.md) | | `venom browser`, `venom acp` | the browser extension; the Agent Client Protocol for editors | the [integrations section](/docs/integrations.md) | | `venom serve` | harness sessions over HTTP and Server-Sent Events for apps | the [server API section](/docs/server-api.md) | | `venom eval`, `venom finetune` | the eval suite, fine-tuning datasets | the [evals section](/docs/evals.md) | ## Names venom shares with pi {#pi-names} venom keeps its state where pi would keep its own, under venom's names: | pi | venom | |---|---| | `~/.pi/` | `~/.venom/` (`VENOM_HOME`) | | `~/.pi/agent/` | `~/.venom/agent/` (`VENOM_CODING_AGENT_DIR`) | | `~/.pi/agent/sessions/` | `~/.venom/agent/sessions/` (`VENOM_CODING_AGENT_SESSION_DIR`) | | a project's `.pi/` | `.venom/` | | `pi` | `venom` | pi's package commands work under the venom name: `venom install `, `venom remove `, `venom list`, `venom update` and `venom auth`. pi's own `config` (which package resources load) is `venom config packages`, because `venom config` shows venom's configuration. ## Exit codes {#exit-codes} Subcommands follow one rule: `0` success, `1` a failure the command reports (a check that did not pass, a conflict, nothing found), `2` a usage error. A flag or endpoint your organisation's policy forbids stops the run before it starts, naming the policy file. A Node.js older than the supported version stops with its own message before anything loads. ## In this section {#in-this-section} - [Flags](/docs/cli/flags.md): Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default. - [Slash commands](/docs/cli/slash-commands.md): Every slash command in a venom session, grouped by what it is for, with its arguments, plus the context commands in detail. - [Keys](/docs/cli/keys.md): The leader key (ctrl+g) and what each key after it does, the direct shortcuts venom adds, pi's own keys, and copying text out of the TUI. - [The terminal UI](/docs/cli/tui.md): What the venom TUI shows and how to change it, from the HUD, call meter, transcript verbosity and reading width to the agents panel, pull requests pane, attachments, sounds and colour themes. - [Plan mode](/docs/cli/plan-mode.md): Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute. - [Print, JSON and RPC modes](/docs/cli/headless.md): Run venom without the TUI, in scripts, CI and other programs, with one printed answer, a JSON event stream or an RPC loop, plus piped stdin, approvals and --json output from subcommands. - [Sessions, resume and export](/docs/cli/sessions.md): Where venom keeps sessions, how to continue, resume, search, replay, export, share and attach to them, and how to find the ones that went wrong. - [Workspaces (git worktrees)](/docs/cli/workspaces.md): Run a session or a subagent in its own git worktree, then merge, apply, open a pull request for or remove its work with venom workspace. - [The agent's tools](/docs/cli/tools.md): The tools the venom agent can call beyond reading, editing and running commands, when each is offered, what it can reach, and the tests it runs after edits. - [Cost, health and routing commands](/docs/cli/insight-commands.md): The venom subcommands that check the setup and explain spend, routing, tool errors, wasted tokens, flaky tests and local models. - [Project setup, memory and onboarding commands](/docs/cli/project-commands.md): Set a project up for venom, keep its memory, index its code, and help new people learn a codebase with tours, explanations and answers that cite their sources. - [Git, review and shipping commands](/docs/cli/git-commands.md): Find the commit that broke a test, try a goal several ways at once, track intents, sign and verify who made a change, revert it, and ship a branch or a stack of them. ================================================================================ # Flags URL: https://cloud.usevenom.dev/docs/cli/flags Description: Every flag the venom command takes, venom's own and the ones it inherits from pi, with what each does and its default. Flags go before or after the prompt: `venom --yolo "fix the build"` and `venom "fix the build" --yolo` are the same. `--` ends option parsing, so a prompt may start with a dash: `venom -p -- "- summarise these points"`. Subcommands (`venom cost`, `venom workspace`, ...) take their own flags, documented with each command. ```bash venom --permission-mode accept-edits -w fix-login "make the login test pass" venom --plan "how would we split the billing module?" venom -p --output-budget 20000 --no-self-review "refactor src/cache.ts and open a PR" ``` ## Permissions and sandbox {#permissions} | Flag | What it does | |---|---| | `--permission-mode ` | Start in this mode: `plan`, `default`, `accept-edits`, `auto`, `yolo` or `sudo`. Claude Code's names work too (`acceptEdits`, `bypassPermissions`, `dontAsk`). `alt+m` cycles the five saved modes in the TUI. | | `--yolo` | Same as `--permission-mode yolo`: no prompts; bash runs in the OS sandbox. | | `--sudo`, `--dangerously-skip-permissions` | Session-only sudo: no prompts at all and bash without the OS sandbox. Deny rules, explicit ask rules, your organisation's policy, the hard-deny list and the secret-path guard still apply. Never saved; `/sudo` or `alt+s` toggles it. | | `--sandbox` | Always run bash inside the OS sandbox (sandbox-exec on macOS, bubblewrap on Linux). | | `--no-sandbox` | Never sandbox bash (`yolo` sandboxes it by default). | | `--plan` | Start in [plan mode](/docs/cli/plan-mode.md): read-only, the plan goes to `.venom/plans/`. | | `--approve`, `-a` | Trust this project's hooks, MCP servers and allow rules for this run only. | | `--no-approve`, `-na` | Ignore this project's trust-gated configuration for this run, even when the project is trusted. | | `--coordinator` | The main agent only reads and delegates: it gets no edit, write, patch or bash tools, and workers (`task` subagents) make the changes. | `--mode` is pi's output mode (`text`, `json`, `rpc`), not a permission mode: `venom --mode accept-edits` stops with a hint to use `--permission-mode`. What each mode allows: | Mode | Behaviour | |---|---| | `plan` | Read-only: reads, searches and read-only bash commands. | | `default` | Reads in the workspace run; edits, writes and bash commands your rules don't allow ask first. | | `accept-edits` | Edits in the workspace run; bash still asks unless a rule allows it. | | `auto` | `accept-edits`, plus a classifier on the fast model decides what `default` would have asked (unlisted bash, MCP and app tools). Needs the OS sandbox, so it is not available on Windows. | | `yolo` | Everything runs except hard denies, your deny and ask rules and protected paths. | | `sudo` | No prompts, no sandbox (see above). Session-only. | Without a terminal (print and JSON modes), an action that would ask is denied, and the model is told which allow rule would permit it. ## Workspaces {#workspaces} | Flag | What it does | |---|---| | `-w`, `--worktree [name]` | Run this session in a new git worktree, `.venom/worktrees/` on branch `venom/`. Without a name venom picks one (`adjective-noun`). The worktree is removed at exit when nothing in it would be lost. | | `--from ` | With `-w`: start the worktree from this ref instead of `HEAD`. | | `--no-worktree` | Don't start in a worktree, even when `workspaces.default` says every session should. | `venom workspace` manages these worktrees afterwards; see its reference page in this section. ## Tools and editing {#tools} | Flag | What it does | |---|---| | `--edit-tool ` | Which file-editing tool the model gets: `auto` (default: `apply_patch` for models trained on OpenAI's V4A patch format, `edit` for the rest), `edit`, `apply_patch` or `both`. `apply_patch` goes through the same permission checks, checkpoints, formatter and diagnostics as `edit`, and a patch applies atomically: a hunk that does not match writes nothing. | | `--offline` | Offline mode: MCP servers are registered disabled and there is no `web_fetch` or `web_search`. Also stops pi's own startup network calls. | | `--chrome` | Every browser tool from the start, in a Chrome window you can watch. | | `--chrome-headless` | Every browser tool from the start, headless. | | `--chrome-attach ` | Browser tools on a Chrome you started with `--remote-debugging-port=` (its logins are in reach). | | `--chrome-extension` | Browser tools on your own Chrome through the venom browser extension, one window per agent (pair it first with `venom browser pair`). | | `--no-chrome` | No browser tools. | Without a browser flag, and with Chrome, Chromium, Edge or Brave installed, the agent gets one browser tool, `browser_navigate`; the rest of the browser tools and a headless browser start on its first call. ## Budgets, review and cost {#budgets} | Flag | What it does | |---|---| | `--output-budget ` | The output tokens this run is meant to use. When the model stops below 90% of it, a message tells it how much it used and to keep going. It stops nudging after three nudges once the last two continuations each produced under 500 tokens, and never nudges in plan mode, in a subagent or after a limit stop. Default: none (venom.yaml `guards.output_budget`). | | `--no-self-review` | Skip the review of the branch's diff that runs before the agent opens a pull request with `gh pr create` (venom.yaml `review.before_pr`, on by default). | | `--task ` | The pull request, issue or tracker key this session's spend counts toward (`venom cost --by task`). Default: the branch's. `/task` changes it in a session. | ## Models and thinking {#models} These are pi's flags; venom's provider resolves them against `VENOM_BASE_URL`. | Flag | What it does | |---|---| | `--model ` | The model: an exact id or a fuzzy match, `provider/id`, with an optional `:` suffix. Beats `VENOM_MODEL`. Default `venom-default`. | | `--provider ` | Look `--model` up in one provider only. venom never uses pi's built-in cloud providers unless you pick one this way or with `/model`. | | `--api-key ` | A key for this run only. | | `--thinking ` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`, clamped to what the model supports. | | `--models ` | Comma-separated models (globs and fuzzy matches) that `ctrl+p` cycles through. | | `--list-models [search]` | List the models the providers serve and exit. | ## Sessions {#sessions} | Flag | What it does | |---|---| | `-c`, `--continue` | Continue the newest session of this directory. | | `-r`, `--resume` | Pick a saved session to resume. | | `--session ` | Open a session by file, id or id prefix. | | `--session-id ` | Open the session with this exact id, creating it if it does not exist. | | `--fork ` | Fork a saved session into a new one. | | `--session-dir ` | Where sessions are stored and looked up (beats `VENOM_CODING_AGENT_SESSION_DIR`). | | `--no-session` | Don't save this session. | | `-n`, `--name ` | The session's display name. | | `--export [out]` | Export a session file to HTML and exit. `venom export` writes the fuller trace. | ## Output and process {#output} | Flag | What it does | |---|---| | `-p`, `--print` | Run the prompt, print the final answer, exit. | | `--mode ` | The output interface: `json` writes every event as a JSON line, `rpc` reads commands on stdin. See [Print, JSON and RPC modes](/docs/cli/headless.md). | | `--tui-mode ` | `fullscreen` (default) or `regular` (the transcript stays in the terminal's scrollback). | | `--verbose` | The full startup header and resource lists (overrides `quietStartup`). | | `-h`, `--help` | venom's help, then pi's. | | `-v`, `--version` | Print the version and exit. | ## Tools, resources and prompt (pi) {#resources} | Flag | What it does | |---|---| | `-t`, `--tools ` | Comma-separated allowlist of tools (`*` patterns). A list of only `+name`/`-name` entries adds to or removes from the defaults. | | `-xt`, `--exclude-tools ` | Tools to disable, MCP tools included. | | `-nt`, `--no-tools` | Start with every tool disabled. | | `-nbt`, `--no-builtin-tools` | Disable pi's built-in tools, keep extension tools. | | `-e`, `--extension ` | Load an extension (repeatable). `venom plugin dev ` is the plugin author's shortcut. | | `-ne`, `--no-extensions` | No discovered or configured extensions (explicit `-e` still loads). | | `--no-mcp` | No MCP servers and no MCP tools for this run. | | `--skill `, `-ns`, `--no-skills` | Load a skill; or load none of the discovered ones. | | `--prompt-template `, `-np`, `--no-prompt-templates` | Load a prompt template; or none of the discovered ones. | | `--theme `, `--use-theme `, `--no-themes` | Load a theme file, pick this run's theme, or load no themes. venom's own themes are chosen with `ui.theme` or `/theme` (see [The terminal UI](/docs/cli/tui.md#themes)). | | `-nc`, `--no-context-files` | Don't load `AGENTS.md` or `CLAUDE.md`. | | `--system-prompt ` | Replace the system prompt. | | `--append-system-prompt ` | Append to the system prompt (repeatable). | ## Input {#input} | Input | What it does | |---|---| | `message …` | The first prompt; several messages are sent one after another. | | `@path` | Include a file or an image in the first prompt. | | piped stdin | Put before the prompt (print mode). `-` as the prompt means "the prompt is on stdin". | ## Environment {#environment} The flags above override the environment. The variables `venom --help` lists: | Variable | What it sets | Default | |---|---|---| | `VENOM_BASE_URL` | the OpenAI-compatible endpoint, including `/v1` | `http://localhost:8787/v1` | | `VENOM_API_KEY` | the key for it | none | | `VENOM_MODEL` | the model for every command (`--model` beats it) | `venom-default` | | `VENOM_FAST_MODEL`, `VENOM_SMART_MODEL` | the fast and smart delegation tiers | `venom-fast`, `venom-smart` | | `VENOM_CONTEXT_WINDOW` | a cap on the context window: the smaller of the server's window and this | `131072` when the server reports none | | `VENOM_MAX_WIDTH` | the chat's width on wide terminals: columns, `auto` (100) or `full` | `auto` | | `VENOM_SOUND_PLAYER` | your own player command for event sounds | `afplay` on macOS; `pw-play`, `paplay` or `aplay` on Linux; PowerShell on Windows | | `VENOM_DEBUG` | `1` prints harness diagnostics, hook messages and compaction steps | off | | `VENOM_ONLINE` | `1` lets pi make its own startup network calls | off | | `VENOM_HOME` | venom's state directory | `~/.venom` | The complete list of venom.yaml keys and environment variables is in the [venom.yaml reference](/docs/configuration/venom-yaml.md) and [environment variables](/docs/configuration/env-vars.md) pages. ## Errors {#errors} | Message | Cause | |---|---| | `Invalid mode` or a hint to use `--permission-mode` | A permission mode was given to `--mode`. | | A session flag conflict | `--fork` cannot be combined with `--session`, `--continue`, `--resume` or `--no-session`; `--session-id` cannot be combined with `--session`, `--continue` or `--resume`. | | A refusal naming the policy file | Your organisation's policy forbids the flag (for example `--sudo`) or the `VENOM_BASE_URL`. | | `auto mode is unavailable; running in …` | `--permission-mode auto` on a machine with no OS sandbox (Windows, or Linux without bubblewrap). There `yolo` also asks before bash commands, as `accept-edits` does. | ================================================================================ # Slash commands URL: https://cloud.usevenom.dev/docs/cli/slash-commands Description: Every slash command in a venom session, grouped by what it is for, with its arguments, plus the context commands in detail. Type `/` in the editor to search the commands loaded in this session: venom's, pi's, your prompt templates, your skills (as `/skill:`) and your plugins'. `/commands` lists the command files and `/skills` the skills. Most commands also work in print mode, where their output goes to stdout: `venom -p /context`. ```text /context what fills the context window /btw what was the port? a side question that doesn't disturb the agent /undo put the files back as they were before the last prompt /branch 4 -w fork the session at turn 4 into a new git worktree ``` ## Context and memory {#context} | Command | What it does | |---|---| | `/context` | Break down the context window: system prompt, tools, memory, skills, conversation, and how close the session is to compaction. | | `/compact [focus]` | Compact the conversation now (pi's command; venom writes the summary). Prints how much it freed. | | `/clear`, `/reset` | Start a fresh conversation, as `/new`. The permission mode, model and gear stay; the old session stays in `/resume`. | | `/forget [n\|id\|all]`, `/drop` | Hide large tool outputs from the context now. Each output is saved to a file and replaced by a stub naming it, so `read` and the `recall` tool still find it. Without an argument it lists the candidates. | | `/pin ` | Pin a fact: every compaction summary carries it word for word. | | `/pins` | List the pinned facts, numbered. | | `/unpin ` | Unpin a fact by its `/pins` number or its text. | | `/btw ` | Ask a side question about the session. It is answered from a copy of the agent's last request in a separate call with no tools, while the agent keeps working. The answer is shown to you only: it never enters the transcript or the model's context. Metered as a `btw` call in `/cost`. | | `/memory [show\|edit\|forget\|path] ` | The project's auto-memory; `/memory org` shows your organisation's facts, `/memory propose ` proposes one. | | `/memory-sync [base]` | Update `AGENTS.md`/`CLAUDE.md` for this branch's change. | | `/summary [show]` | Write this session's summary now (goal, outcome, files touched, cost), or show the last one. | Compaction starts automatically. Where it starts, and whether an idle session compacts in the background, is set in venom.yaml: `context.autocompact` (a share of the window, or `off`), `context.quality` (per-model `soft` and `hard` thresholds, for example `context.quality.*.soft` and `context.quality.*.hard`), and `context.idle_compact` (seconds idle before a context past the soft threshold is compacted; default 180, or `off`; `context.idle_compact.after` and `context.idle_compact.headless` as an object). `VENOM_CONTEXT_WINDOW` caps the window venom assumes. When the context passes 80% of the window the TUI says so once. ## Files and checkpoints {#checkpoints} | Command | What it does | |---|---| | `/undo` | Undo the file changes of the last prompt: the files go back to the checkpoint taken before it. | | `/redo` | Re-apply what the last `/undo` reverted. | | `/checkpoints` | List this branch's file checkpoints. | | `/rewind` | Pick an earlier point of the conversation (pi's `/tree`); venom asks whether to restore the files to it too. | ## Branches and bookmarks {#branches} | Command | What it does | |---|---| | `/bookmark [name]` | Bookmark the latest turn. `/bookmark -d ` removes one. | | `/bookmarks [name\|turn]` | List bookmarks, or jump to one. | | `/branch [turn\|bookmark] [-w [name]]` | Fork the session at a turn or bookmark into a new branch session. With `-w`, or when the session runs in a workspace, the branch gets its own git worktree. `/fork ` is the same; a bare `/fork` is pi's picker. | | `/branches [n]` | The tree of branch sessions (`/fork`, `/branch`, `/clone`); `/branches 2` switches to one. | Bookmarks and branch headers are labels on the session, not messages: none of this reaches the model. ## Sessions {#sessions} | Command | What it does | |---|---| | `/new` | Start a new session. | | `/resume` | Switch to another saved session. | | `/name [name]` | Set or show the session's name. | | `/session` | The session's file, id and statistics. | | `/tree` | Navigate the session tree. | | `/fork`, `/clone` | Fork from an earlier message; duplicate the session at this point. | | `/import ` | Import and resume a JSONL session. | | `/export [html\|md\|jsonl\|otlp-json] [path] [--raw]` | Write this session's full trace, secrets scrubbed unless `--raw` (as `venom export`). | | `/share` | Share this session on Venom Cloud, redacted first (as `venom session share`). `/share live` lets teammates watch it as it runs; `/share live stop` ends that. venom never uploads to pi's gist viewer. | | `/copy [N]` | Copy the latest (or Nth-latest) answer to the clipboard, with a picker of its code blocks. | | `/handoff @name [message]` | Hand the session to a teammate (Venom Cloud). | | `/quit` | Quit. | ## Pairing {#pairing} Two people and one agent, taking turns. Needs `venom cloud login`; the session is shared live on Venom Cloud. | Command | What it does | |---|---| | `/pair @alice [--first me\|them]` | Start pairing with a teammate; `--first` says who drives first. `/pair end` stops, `/pair status` shows who drives. | | `/pass [me\|them]` | Pass the driver token to your partner, or take it back. Only the driver's messages reach the agent. | | `/comments` | Your partner's comments waiting for you. While your partner drives, what you type goes to them as a comment. | | `/include ` | Add your partner's comments to your next message. Comments reach the model only this way. | ## Agents and work {#agents} | Command | What it does | |---|---| | `/agents` | The subagents the `task` tool can start. | | `/subagents [on\|off\|toggle]` | Multiple subagents mode: off stops the agent from delegating. | | `/agents-panel [on\|off\|auto\|legend]` | The live agents panel (see [The terminal UI](/docs/cli/tui.md#agents-panel)). | | `/ps`, `/top` | This session's agents: state, wait reason, turns, tools, tokens, cost; `/top` sorts by token rate since the last `/top`. | | `/plan [task\|accept]` | Toggle [plan mode](/docs/cli/plan-mode.md); `/plan ` starts planning, `/plan accept` executes the plan. | | `/plan-exec` | Plan, approve, then run each step on a worker and verify it. | | `/task ` | The pull request, issue or tracker key this session's spend counts toward. | | `/workspace [list\|new\|switch\|diff\|merge\|apply\|pr\|push\|rm]` | Git worktrees (as `venom workspace`). | | `/workflow` | List or run the project's workflow scripts (`.venom/workflows`). | | `/template` | Start from a saved setup: prompt, gear, tools, checks. | | `/review`, `/security-review` | A read-only review, or security review, of the working-tree diff (`--staged`, `--base `, a range). | | `/ship [--no-merge] [--title t]` | Gate plan, evidence, pull request and merge queue for this branch (as `venom ship`). | | `/board [prefix]` | The board's notes, with a team's task list summary. | | `/fleet` | Your agents and your teammates' on this repository (Venom Cloud). | | `/init` | Analyse the project and write `AGENTS.md` and starter permission rules (as `venom init`). | | `/browser record ` | Record a browser task to replay later without the model (`record stop`, `scripts`, `show`, `edit`, `delete`). | | `/chart [type]`, `/chart ` | Draw a chart in the transcript from a `.csv`, `.tsv`, `.json` or `.yaml` file, or from a spec. The agent draws the same charts with its `chart` tool or a fenced `chart` block. Charts are UI only: they never enter the model's context. | ## Models, modes and settings {#settings} | Command | What it does | |---|---| | `/model [provider/model]` | Pick a model. | | `/thinking [level]` | Set the thinking level. | | `/gear [name]` | Shift gears (`/gear new`, `/gear save `, `/gear edit `, `/gear rm `). | | `/mode [mode]` | Show or set the permission mode. | | `/permissions` | The permission mode, active rules and where each came from. | | `/sudo` | Toggle sudo for this session (no prompts, no sandbox). | | `/offline [local\|back]` | Offline mode: status, switch now, or go back. | | `/config [sentence]` | The effective configuration and each value's source; a sentence ("warn me above $3 a session") drafts a change and asks before writing it. | | `/guardrails` | Your organisation's guardrails. | | `/mcp-connect [name…] [--force]` | Sign in to your organisation's MCP servers. | | `/library` | The team library from Venom Cloud; its prompts run as `/org:`. | | `/plugins` | venom plugins: scope, state, what each adds. | | `/settings`, `/scoped-models`, `/login`, `/logout`, `/reload`, `/hotkeys`, `/changelog`, `/trust` | pi's settings, model cycling list, provider sign-in, reload, key list, changelog and project trust. | ## Display {#display} | Command | What it does | |---|---| | `/hud [compact\|full\|auto\|custom]` | The status bar layout. | | `/meter [on\|off\|compact\|full]` | The per-call line under each turn. | | `/verbose [quiet\|normal\|full]` | How much of each turn the transcript shows. | | `/width ` | The chat's width on wide terminals. | | `/theme [name\|next\|auto]` | The colour theme. | | `/sounds [play \|mute\|unmute\|toggle]` | Event sounds. | | `/prs [left\|right]` | The pull requests pane. | | `/voice` | Dictate into the editor; `/voice` again stops. | [The terminal UI](/docs/cli/tui.md) explains each of these. ## Cost and routing {#cost} | Command | What it does | |---|---| | `/cost` | This session's tokens and cost. `/cost today\|week\|month [--by gear\|model\|role\|day\|session\|task]` is your spend over days (as `venom cost`). | | `/usage` | Spend and budgets for your key: this session, today, 7 days, this month. | | `/explain-cost` | Why this session cost what it did. | | `/routes [1h\|24h\|7d] [alias]` | Where the orchestrator sent your requests and why. | ## Errors {#errors} | Symptom | Cause | |---|---| | A command's text went to the model as a prompt | The command isn't loaded in this session (a plugin is off, or the project is untrusted). `/commands` and `/plugins` show what is. | | `/btw: nothing to answer from yet` | `/btw` needs one request to the agent first. | | `/undo` finds no checkpoint | The last prompt changed no files through venom's file tools. | | `/forget`: the agent is still working | Wait for the run to end (or press Esc), then `/forget`. | | `/pair` fails | Not signed in: run `venom cloud login`. | ================================================================================ # Keys URL: https://cloud.usevenom.dev/docs/cli/keys Description: The leader key (ctrl+g) and what each key after it does, the direct shortcuts venom adds, pi's own keys, and copying text out of the TUI. venom's keys come in two kinds: the **leader** (a tmux-style prefix: press `ctrl+g`, let go, then one key) and direct shortcuts. The leader works in every terminal, including ones where `alt` doesn't reach the app (iTerm2's default Option key, for one), so every venom action has a leader binding. ```text ctrl+g m cycle permission modes ctrl+g 2 shift to gear 2 ctrl+g ? list every leader binding ctrl+g ctrl+g pi's external editor (the leader twice sends ctrl+g itself) ``` ## The leader's bindings {#leader} Press `ctrl+g ?` in a session for the list as configured. The defaults: | Keys | What they do | |---|---| | `ctrl+g 1` … `ctrl+g 9` | Shift to gear 1–9. | | `ctrl+g up`, `ctrl+g +`, `ctrl+g =` | Shift up a gear. | | `ctrl+g down`, `ctrl+g -` | Shift down a gear. | | `ctrl+g g` | Pick a gear from a list. | | `ctrl+g m` | Cycle the permission mode (same as `alt+m`). | | `ctrl+g M` | Toggle multiple subagents mode (`/subagents toggle`). | | `ctrl+g s` | Toggle sudo: no prompts, no sandbox (same as `alt+s`). | | `ctrl+g a` | Show or hide the agents panel (same as `alt+a`). | | `ctrl+g o` | List this session's agents (`/ps`). | | `ctrl+g b` | The board's notes (`/board`). | | `ctrl+g w` | Switch the chat between the capped reading width and the full terminal width. | | `ctrl+g W` | List the git worktrees venom made (`/workspace list`). | | `ctrl+g u` | Commit and push the current workspace upstream (`/workspace push`). | | `ctrl+g v` | Cycle the transcript verbosity (`/verbose`). | | `ctrl+g h` | Switch the HUD between compact and full (`/hud`). | | `ctrl+g t` | The next colour theme (`/theme next`). | | `ctrl+g c` | Copy the latest answer (`/copy`). | | `ctrl+g n` | Mute or unmute sounds (`/sounds toggle`). | | `ctrl+g x` | Clear the images and files attached to the prompt you are writing. | | `ctrl+g p` | Show or hide the pull requests pane (`/prs`; from the bundled pull requests plugin). | | `ctrl+g ?` | The cheat sheet: every binding as configured. | | `ctrl+g ctrl+g` | Send `ctrl+g` itself: pi's external editor. | | `ctrl+g Esc` | Cancel. | A key that isn't bound cancels the leader, as does waiting longer than the timeout (1.5 seconds by default). While the leader waits, the HUD shows it. The leader key, its timeout and its bindings are set in venom.yaml under `keys`: `keys.leader` (default `ctrl+g`), `keys.leader_timeout_ms` (default `1500`) and `keys.leader_bindings`, a map from a key to an action. An action is `gear `, `mode`, `sudo`, `panel`, `width`, `verbose`, `theme`, `copy`, `attach clear`, `help` or any slash command (`/cost today`); `null` or `none` removes a default. Plugins can add bindings for keys that are still free. `keys.gear_hotkeys: false` turns off the direct gear shortcuts below. ```yaml keys: leader: ctrl+b leader_bindings: r: /routes 1h t: null ``` ## Direct shortcuts {#shortcuts} | Key | What it does | |---|---| | `alt+m` | Cycle the permission mode: plan, default, accept-edits, auto, yolo. | | `alt+s` | Toggle sudo for this session. | | `alt+a` | Show or hide the agents panel. | | `alt+1` … `alt+9` (`alt+`) | Shift to gear 1–9. | | `alt+.`, `alt+,` | Shift up, down a gear. | | `shift+F1` … `shift+F12` | Shift to gear 1–12 (xterm-style terminals, iTerm2, Ghostty, WezTerm, kitty, Windows Terminal, tmux; not rxvt or the Linux console). | ## pi's keys {#pi-keys} The keys pi binds keep working. The ones used most: | Key | What it does | |---|---| | `Esc` | Interrupt the agent. | | `ctrl+c` | Clear the editor; twice to exit. With a selection, copy it. | | `ctrl+d` | Exit (empty editor). | | `shift+tab` | Cycle the thinking level. | | `ctrl+l` | Pick a model. | | `ctrl+p`, `shift+ctrl+p` | Cycle through the models of `--models`. | | `ctrl+o` | Expand tool output, thinking and the startup header. | | `ctrl+t` | Collapse or expand thinking blocks. | | `alt+enter` | Queue a follow-up message for after the run. | | `alt+up` | Put queued messages back in the editor. | | `ctrl+v` | Paste an image, files or text from the clipboard. | | `shift+enter`, `ctrl+j` | New line in the editor. | | `ctrl+shift+f` | Search the transcript (fullscreen). | | `ctrl+z` | Suspend to the background. | | `/` | Commands. | | `!` | Run a shell command. | `/hotkeys` lists every active key. pi's keys are rebound in `~/.venom/agent/keybindings.json`. ## Copying text {#copy} The TUI is fullscreen by default and tracks the mouse, so a plain drag selects inside venom instead of in the terminal. Drag, double-click a word or triple-click a line; the selection is copied on release: - on your own machine, through the system clipboard tool; - inside tmux, into tmux's buffer (and through tmux to the outer terminal's clipboard); - over ssh, through OSC 52. `ctrl+c` with a selection copies it and clears the selection. `/copy` (or `ctrl+g c`) copies the latest answer, `/copy 2` the one before it, with a picker of its code blocks when it has any. For terminal-native selection, start with `--tui-mode regular`. ## Troubleshooting {#troubleshooting} | Symptom | Fix | |---|---| | `alt+m` types a character | Your terminal sends Option as a character (iTerm2's default). Use `ctrl+g m`, or set Option to send Esc+. | | `shift+F3` does something else | rxvt, the Linux console and some Terminal.app setups send other codes. Use `ctrl+g 3` or `alt+3`. | | `ctrl+g` no longer opens the external editor | It is the leader: press it twice. | | Copy doesn't reach the clipboard in tmux | Update tmux, or `set -g set-clipboard on`; OSC 52 needs the outer terminal's support. | ================================================================================ # The terminal UI URL: https://cloud.usevenom.dev/docs/cli/tui Description: What the venom TUI shows and how to change it, from the HUD, call meter, transcript verbosity and reading width to the agents panel, pull requests pane, attachments, sounds and colour themes. Running `venom` in a terminal opens the TUI: a header, the transcript, the editor and the HUD (the status bar) at the bottom. Every display setting below is a preference: the command that changes it saves it, and the next session starts with it. None of it enters the model's context, so changing the display never changes what the model is sent or breaks its prompt cache. ```text /hud full the multi-line status bar /meter full one line per model call under each turn /verbose normal every tool call, thinking in full /width 120 a wider reading column /theme pick a colour theme with a live preview ``` ## The header {#header} The startup header shows the venom version, the model and permission mode, the working directory and a one-line summary of what loaded (context files, skills, commands, the leader key). `ctrl+o` expands it to every key hint and the full lists of context files, skills and prompt templates. `quietStartup: true` in `~/.venom/agent/settings.json` hides it; `--verbose` shows it anyway. ## The HUD {#hud} The HUD is the status bar: context use, spend today and this month, tokens in and out, cache, model, gear, permission mode, thinking level, elapsed time, session cost, directory, git branch, risk tier, leases, running shells and agents, and a clock. Each field has a text label and its own colour, so colour is never the only signal; on a narrow terminal the lowest-priority fields go first. | Layout | What it is | |---|---| | `auto` (default) | `full` on a terminal of at least 24 rows and 60 columns, else `compact`. | | `compact` | One line. | | `full` | Several lines (holds down to 12 rows and 40 columns). | | `custom` | Your own lines of fields, from `ui.hud_lines` in venom.yaml. | `/hud` with no argument switches between compact and full; `/hud compact|full|auto|custom` picks one; `ctrl+g h` is the leader binding. The choice is saved as `ui.hud`. The context gauge turns to warning and critical colours at the thresholds in `ui.hud_thresholds`. Colour follows the theme: `NO_COLOR` turns it off, `FORCE_COLOR` forces a level, a 16-colour terminal gets a basic palette. ## The call meter {#meter} After each turn, the meter adds one dim line per model call made during it: the agent's own, each subagent's, and venom's side requests (the auto-mode classifier, image descriptions, compaction summaries, prompt hooks, `/btw`), each with the model that answered, tokens, cost and time: ```text ▸ gpt-5.4-mini · 12k↑ 9.8k⚡ 312↓ · $0.003 · 1.8s ▸ explorer gpt-5.4-nano · 3.1k↑ 120↓ · $0.0004 · 0.9s ▸ escalated to smart: tests failed · worker · +$0.042 · passed ``` `/meter on|off|compact|full` sets it (default `compact`; no argument switches it on or off). With `off` the calls are still counted, so the HUD's session total stays right. ## Transcript verbosity {#verbosity} | Level | What a turn shows | |---|---| | `quiet` (default) | Each run of tool calls as one line (`● Read 4 files, ran 3 shell commands`), failures under it, each edited file as a diffstat line, each stretch of thinking as its title. | | `normal` | Every tool call the way pi draws it, and thinking in full. | | `full` | Everything expanded. | `/verbose quiet|normal|full` sets it; `/verbose` alone (or `ctrl+g v`) cycles. A click on a group's line expands it; `ctrl+o` expands everything for a moment. The final answer, errors and permission prompts always show in full. ## Reading width {#width} On a wide terminal the transcript and the editor sit in a left-aligned column of at most 100 columns, so prose keeps a readable line length; the HUD stays full width and the agents panel moves into the margin. `/width 120` sets the column, `/width auto` goes back to 100, `/width full` uses the whole terminal; `ctrl+g w` switches between the cap and full. `VENOM_MAX_WIDTH` (columns, `auto` or `full`) wins over the saved setting. ## Agents and subagents {#agents-panel} The main agent delegates with the `task` tool: each subagent starts with an empty context, does one job and reports back. venom ships the `explorer`, `worker` and `verifier` agents; your own and a project's agents load beside them (`/agents` lists them). Per-agent settings go under `agents` in venom.yaml: ```yaml agents: explorer: model: fast # a tier (fast, smart, inherit), an alias or a model id verifier: model: smart ``` The **agents panel** is a column on the right listing the session's agents as a tree, each with its role, model, status, how long it has run and what it is doing now. | Command or key | What it does | |---|---| | `alt+a`, `ctrl+g a` | Show or hide the panel. | | `/agents-panel on\|off\|auto` | Keep it on, off, or show it while subagents run and the terminal has room (`auto`, default); saved as `ui.agents_panel`. | | `/agents-panel legend` | What the glyphs and colours mean. | | `/ps`, `ctrl+g o` | A table of the session's agents: state, wait reason, turns, tools, tokens, cost. | | `/top` | The same, sorted by token rate since the last `/top`. | | `/subagents on\|off\|toggle`, `ctrl+g M` | Multiple subagents mode. Off, the agent works alone and the `task` tool refuses; the HUD shows `multi off`. | | `/agents` | The agents the `task` tool can start. | ## The pull requests pane {#prs} The bundled pull requests plugin shows your open pull requests beside the chat, through the `gh` CLI (signed in with `gh auth login`). `/prs` or `ctrl+g p` shows or hides it; `/prs left` and `/prs right` pick the side. Its side, width and refresh are saved under `ui.pr_pane`. ## Attachments {#attachments} `ctrl+v` pastes an image from the clipboard as `[Image #1]`; pasting or dropping file paths turns images into `[Image #n]` chips and other files into `@path` mentions the agent reads. A chip moves and deletes as one unit; delete it to leave the image out. `ctrl+g x` clears every attachment of the prompt you are writing. A model without image input gets each image described by the vision model (`VENOM_VISION_MODEL`). ## Sounds {#sounds} venom plays a sound when the main agent finishes, a subagent finishes, a permission prompt waits or a run fails, by default only while the terminal is unfocused. Sounds play in the TUI only, never in print mode, `venom serve` or ACP. | Command | What it does | |---|---| | `/sounds` | List the sounds; pick one to preview, or mute. | | `/sounds play ` | Play one. | | `/sounds mute\|unmute\|toggle`, `ctrl+g n` | For this session. | | `venom sounds list [--play ]` | The same list from the shell, with the configuration and the player venom found. | The built-in sounds are synthesized: `chime` (main agent done), `done`, `tick` (subagent done), `pop` (step done, off by default), `bell`, `hiss`, `success`, `failure` (run failed), `attention` (permission needed) and `marimba`. Any audio file path works as a custom sound. Which event plays what, the volume, quiet hours and the focus rule are the `sounds` keys in venom.yaml; `VENOM_SOUND_PLAYER` sets your own player (`mpv --no-video`). Hooks can play sounds too. ## Themes {#themes} Sixteen built-in colour themes, ten dark and six light: `venom-night` (the dark default), `venom-dusk`, `amber-night`, `high-contrast`, `colorblind`, `venom-classic`, `low-glare`, `deep-sea`, `forest-night`, `obsidian`, `venom-light` (the light default), `sepia-paper`, `daylight`, `high-contrast-light`, `colorblind-light` and `sage-light`. The default setting, `auto`, picks `venom-night` or `venom-light` from the terminal's background. | Command | What it does | |---|---| | `/theme` | Pick a theme with a live preview. | | `/theme `, `/theme next`, `/theme auto` | Set one, take the next (`ctrl+g t`), or follow the terminal. Saved as `ui.theme`. | | `venom theme list` | The themes, where each comes from, the one in use. | | `venom theme show ` | Its colours and their WCAG contrast ratios. | | `venom theme preview [name] [--all]` | A sample of the HUD, agents panel, meter and `/usage` in it. | | `venom theme tokens` | Every token a theme or `ui.theme_overrides` can set. | | `venom theme new [--base ] [--light\|--dark] [--project]` | Write a commented starter theme to `~/.venom/themes/.yaml` (`.venom/themes/` with `--project`); never overwrites. | | `venom theme check ` | Validate a theme file, with its contrast ratios. | | `venom theme schema` | The theme file's JSON Schema. | Themes are data, not code, so a project's themes in `.venom/themes/` load without trusting the project. Plugins can ship themes too. ## Troubleshooting {#troubleshooting} | Symptom | Fix | |---|---| | Old frames pile up in the scrollback | venom drops the full-screen clear that iTerm2, Terminal.app and PuTTY copy into the scrollback. If you still see it, try `--tui-mode regular`. | | No colours | `NO_COLOR` is set, or `TERM=dumb`. `FORCE_COLOR=3` forces truecolor. | | No sounds | Muted (`/sounds`), `sounds.enabled: false`, the terminal is focused, or no player was found (`venom sounds list` names the player). | | The PR pane is empty | `gh` isn't installed or signed in. | ================================================================================ # Plan mode URL: https://cloud.usevenom.dev/docs/cli/plan-mode Description: Have the agent investigate read-only and write a plan before it changes anything, then approve the plan and let it execute. Plan mode is the read-only permission mode. The agent reads, searches and runs read-only commands, writes its plan to a file under `.venom/plans/`, and asks you to approve it. Nothing else in the workspace can change until you do. ```bash venom --plan "add rate limiting to the public API" ``` In a session: ```text /plan add rate limiting to the public API enter plan mode and start planning /plan accept leave plan mode and execute the plan /plan toggle plan mode ``` `alt+m` (or `ctrl+g m`) also cycles into and out of `plan`, and `--permission-mode plan` starts there. ## How a plan is made {#flow} 1. In plan mode only reads, searches and allowlisted read-only bash commands run. The one place the agent can write is `.venom/plans/`; bash cannot write there. 2. The agent writes the plan to `.venom/plans/-