Skip to content
Docs menu

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.

View .md

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 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

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) 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:<id> or session:<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_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

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:

  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.

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 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=<hex> (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=<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).