---
title: Build on Venom 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.
section: developers
order: 130
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/flags/mcp, services/nodejs-cloud/lib/flags/auth.ts, services/nodejs-cloud/lib/flags/access.ts, services/nodejs-cloud/lib/flags/http.ts, services/nodejs-cloud/lib/flags/webhooks.ts, services/nodejs-cloud/app/flags/api/v1, services/nodejs-cloud/app/flags/sdk, services/nodejs-cloud/app/flags/mcp/route.ts, services/nodejs-cloud/contracts/flags-openapi.yaml, services/nodejs-cloud/lib/oauth, docs/adr/0053-venom-flags.md]
features: []
---

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:<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](/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 `#<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 {#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: "<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](/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 `<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 {#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).
