Build on Venom Flags
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
- 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 withPATCH /flags/api/v1/projects/{project}/flags/{key}. - An agent that runs a rollout. Connect
venom-flagsand let an agent callflags_flag_preview,flags_flag_rolloutandflags_flag_revertif 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=productionorflags_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 andflags_coderef_listshow 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
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
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:<key id> |
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:<key id> |
flags:read and flags:write; never flags:admin |
| OAuth app | the app's name, mcp:<client id>:<member> |
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) carriesflags:readandflags:writebut neverflags:admin, so admin tools refuse it. A token for theflagsresource (/flags/mcp) can carryflags:admin, and only such a token works on/flags/api/v1. - A request with an API key can send
x-venom-agent: daemon:<id>orsession:<id>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. - If the org has not added Flags, each REST call answers
403 addon_requiredand each tool says where to add it.GET /flags/api/v1/mealways 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 get429withRetry-After.
A refused write is 403 over REST, or a tool error that names the missing permission over MCP.
Worked example
Create a temporary boolean flag, serve it to 20 % of users in staging, then check what one user gets:
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:
{ "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 #<index>) 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
Every write takes the same options, over REST (headers or body) and MCP (arguments):
| Option | REST | MCP | What it does |
|---|---|---|---|
| Version check | If-Match: "<version>" 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:
flags_flag_getthe flag and note itsversion.flags_flag_previewthe instructions andflags_flag_evaluatetwo or three real contexts.flags_flag_update(orflags_flag_toggle,flags_flag_rollout) withexpectVersionand acommentsaying why.- If something goes wrong,
flags_flag_historyshows the change andflags_flag_revertundoes 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.
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
3 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| 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
<kind>.<action>:flag.create,flag.update,flag.delete,flag.revert, and the same forsegment,environment,projectandwebhook. Rotating a key sendsenvironment.rotate_sdk_key,environment.rotate_mobile_keyorenvironment.rotate_client_key. Archiving and restoring a flag areflag.update. - Body:
{"event": "flag.update", "tenant": "…", "entry": {…}}, whereentryis 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=<hex>(HMAC-SHA256 of the raw body with the webhook's secret). - Delivery: 5 second timeout, no redirects followed, any
2xxcounts. A failure is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then dropped. The URL must behttps(orhttponlocalhostor127.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=<seq> or flags_flag_history with since return
the entries after a sequence number.
REST routes
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.
MCP 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).
Related
- Venom Flags: the app, targeting, stale flags and who can do what.
- SDK and REST API: keys, SDKs, the SDK endpoints, code references in CI and errors.
- Build on Venom Experiments: A/B tests that run through a flag's rollout.
- Authentication and scopes, Errors, limits and pagination, Webhooks and events and MCP.