---
title: Venom Flags SDK and REST API
description: Evaluate Venom Flags in your own code with the TypeScript, Python or Go SDK or the client-side endpoint, report where flags are used from CI, and read and change flags, segments and environments over the REST API with curl.
section: cloud
order: 247
audience: [builder, agent, user]
sources: [services/nodejs-cloud/sdk/flags, services/nodejs-cloud/sdk/flags/python/venom_flags.py, services/nodejs-cloud/sdk/flags/go, services/nodejs-cloud/sdk/flags/code-refs.mjs, services/nodejs-cloud/contracts/fixtures/flags/eval-vectors.json, services/nodejs-cloud/app/flags/sdk, services/nodejs-cloud/app/flags/api/v1, services/nodejs-cloud/lib/flags/http.ts, services/nodejs-cloud/lib/flags/contract.ts, services/nodejs-cloud/contracts/flags-openapi.yaml]
features: [cloud.flags]
---

[Venom Flags](/docs/cloud/flags.md) has two kinds of HTTP surface:

- **SDK endpoints** (`/flags/sdk/…`), which your application calls with an environment's SDK key to get flag values.
- **The REST API** (`/flags/api/v1/…`), which people, scripts, CI and agents call with a Venom API key to read and
  change flags. Agents can also use the [MCP server](/docs/developers/flags.md), which covers the same ground in fewer calls.

The examples use `https://cloud.usevenom.dev`. A self-hosted Venom Cloud serves the same paths on its own origin.
`/flags/quickstart` in the app shows these examples with your project and environments filled in.

## Keys

Each environment has three credentials, on `/flags/settings`:

| Key | Prefix | Use it in | Secret? |
|---|---|---|---|
| Server-side SDK key | `vfs_` | your servers, with the SDK | yes: shown once, when created or rotated |
| Mobile key | `vfm_` | mobile apps that download the ruleset | yes: shown once |
| Client-side id | `vfc_` | browsers, for the client-side endpoint | no: it only reads flags marked client-side |

The REST API takes a Venom API key (`vck_…`, from Settings → API keys) or an OAuth token for the `flags` resource.
Keep keys out of files you commit; the examples read them from environment variables.

## The TypeScript SDK

The server SDK downloads the environment's ruleset once, keeps it current over a stream, and evaluates every flag in
your process with the same evaluator the cloud runs. A flag check is a function call, not a network request, and it
keeps working with the last ruleset if the cloud is unreachable. It has no dependencies (Node 20 or later). It ships
as source in the cloud's repository (`services/nodejs-cloud/sdk/flags`, with `lib/flags/eval.ts` and
`lib/flags/contract.ts`): copy those into your project or import them from a checkout.

```ts
import { VenomFlags } from "./venom-flags/sdk/flags/index.ts";

const flags = new VenomFlags({
  sdkKey: process.env.VENOM_FLAGS_SDK_KEY!, // vfs_…
  baseUrl: "https://cloud.usevenom.dev",
});
await flags.ready(5_000);

const user = { kind: "user", key: "u-123", email: "ada@example.com", plan: "pro" };
if (flags.boolVariation("new-checkout", user, false)) {
  // the new code path
}

const color = flags.stringVariation("button-color", user, "blue");
const detail = flags.variationDetail("new-checkout", user, false); // { value, variation, reason }

flags.on("update", ({ changed }) => console.log("flags changed:", changed));
await flags.close(); // on shutdown
```

- `ready(timeoutMs?)` resolves once the first ruleset arrived, and rejects when the key is refused or the timeout
  passes. Before the first ruleset, every call returns your fallback with the reason `CLIENT_NOT_READY`.
- `variation`, `boolVariation`, `stringVariation`, `numberVariation`, `jsonVariation` return the value; the typed
  ones return the fallback when the value has another type. `variationDetail` adds the variation index and the reason (`OFF`, `TARGET_MATCH`,
  `RULE_MATCH` with the rule's index and id, `FALLTHROUGH`, `PREREQUISITE_FAILED`, `ERROR`).
- `allFlags(context)` returns every flag's value for a context, for example to pass to a page (not counted).
- `flush()` sends the evaluation counts now; `close()` stops the stream and sends the last of them.
- Options: `stream` (default `true`; `false` polls), `pollIntervalMs` (default 30 s), `eventsFlushMs` (how often
  evaluation counts are sent, default 30 s; `0` never sends them), `fetch`, `onError`.

### Contexts

A context is who or what a flag is evaluated for. It has a `kind` (default `user`), a `key`, and any attributes your
rules use:

```json
{ "kind": "user", "key": "u-123", "email": "ada@example.com", "plan": "pro", "country": "NZ" }
```

To target by more than one kind at once, send a multi-kind context:

```json
{ "kind": "multi", "user": { "key": "u-123" }, "org": { "key": "acme", "tier": "gold" } }
```

`user`, `org` and `device` are built in; any other kind works too.

## The Python SDK

`services/nodejs-cloud/sdk/flags/python/venom_flags.py` is one file with no dependencies (Python 3.9 or later).
Copy it into your project. It does what the TypeScript SDK does: downloads the ruleset, follows the stream (or
polls), evaluates in your process and sends evaluation counts.

```python
import os
from venom_flags import VenomFlags

flags = VenomFlags(os.environ["VENOM_FLAGS_SDK_KEY"], "https://cloud.usevenom.dev")
flags.ready(5)  # raises TimeoutError, or VenomFlagsError when the key is refused

user = {"kind": "user", "key": "u-123", "plan": "pro"}
if flags.bool_variation("new-checkout", user, False):
    ...  # the new code path
detail = flags.variation_detail("new-checkout", user, False)  # {"value", "variation", "reason"}
flags.on_update(lambda e: print("flags changed:", e["changed"]))
flags.close()  # on shutdown
```

- Options: `stream=True` (`False` polls), `poll_interval=30` and `events_flush=30` in seconds (`0` never sends
  counts), `timeout=10` per request, `on_error`.
- `variation`, `bool_variation`, `string_variation`, `number_variation`, `json_variation`, `variation_detail`,
  `all_flags`, `flush` and `close` behave as their TypeScript counterparts. The client is thread-safe and works as a
  context manager (`with VenomFlags(…) as flags:`).
- `evaluate(flag, context, ruleset)` and `evaluate_all(ruleset, context)` are the bare evaluator, for a ruleset you
  fetched yourself.

## The Go SDK

`services/nodejs-cloud/sdk/flags/go` is a Go module of its own, package `venomflags`, standard library only. Vendor
the directory or point a `replace` directive at a checkout.

```go
import venomflags "github.com/elishahbiz/venom/services/nodejs-cloud/sdk/flags/go"

client, err := venomflags.New(venomflags.Config{
	SDKKey:  os.Getenv("VENOM_FLAGS_SDK_KEY"), // vfs_…
	BaseURL: "https://cloud.usevenom.dev",
})
if err != nil {
	log.Fatal(err)
}
defer client.Close()
if err := client.Ready(5 * time.Second); err != nil {
	log.Print(err) // venomflags.ErrNotReady or venomflags.ErrKeyRefused; calls serve the fallback until ready
}

user := venomflags.Context{"kind": "user", "key": "u-123", "plan": "pro"}
if client.BoolVariation("new-checkout", user, false) {
	// the new code path
}
detail := client.VariationDetail("new-checkout", user, false) // Value, Variation, Reason
```

- `Config`: `DisableStream` (poll instead), `PollInterval` and `EventsFlush` (default 30 s; a negative
  `EventsFlush` never sends counts), `RequestTimeout` (default 10 s), `HTTPClient`, `OnError`.
- `Variation`, `BoolVariation`, `StringVariation`, `NumberVariation`, `JSONVariation`, `VariationDetail`,
  `AllFlags`, `OnUpdate`, `Flush` and `Close`. Safe for concurrent use.
- `venomflags.Evaluate(flag, ctx, ruleset)` and `EvaluateAll` are the bare evaluator.

## Other languages

Every SDK evaluates against the same vectors: `services/nodejs-cloud/contracts/fixtures/flags/eval-vectors.json`
holds rulesets and, for each case, the context and the exact value, variation and reason the cloud's evaluator
gives, every operator, segments, prerequisites, rollouts and errors included, plus the bucketing hash itself. The
TypeScript, Python and Go SDKs run all of it in their tests. To write an SDK in another language, download the ruleset,
follow the evaluation order on the [Venom Flags](/docs/cloud/flags.md) page, and pass the vectors. Two details matter most:
a rollout buckets a context with `sha1("<flagKey>.<salt>.<value>")` (or `"<seed>.<value>"`), the first 15 hex digits
divided by `0xFFFFFFFFFFFFFFF`; and `before` / `after` read RFC 3339 timestamps strictly (a real calendar date, hours
0 to 23, the fraction cut to milliseconds) or numbers as milliseconds.

## SDK endpoints

| Method and path | Credential | Answers |
|---|---|---|
| `GET /flags/sdk/ruleset` | `Authorization: vfs_…` or `vfm_…` | the environment's flags and segments. `ETag` is the environment's version; send `If-None-Match` to get `304` when nothing changed |
| `GET /flags/sdk/stream` | the same | Server-Sent Events: `put` with the ruleset on connect, `ping` when it changes (refetch with your ETag). Ends after about 5 minutes; reconnect |
| `POST /flags/sdk/evaluate` | `x-venom-client-id: vfc_…` (or an SDK key) | values of the flags marked client-side, for the posted `{ "context": … }`. CORS is open, for browsers |
| `POST /flags/sdk/events` | an SDK key or client-side id | `202`. Body: evaluation summaries (counts per flag, variation and version), which feed Insights |

From a browser:

```bash
curl -s https://cloud.usevenom.dev/flags/sdk/evaluate \
  -H "x-venom-client-id: $VENOM_FLAGS_CLIENT_ID" -H "content-type: application/json" \
  -d '{"context": {"kind": "user", "key": "u-123"}}'
```

```json
{ "new-checkout": { "value": true, "variation": 0, "version": 7 } }
```

## Code references in CI

`services/nodejs-cloud/sdk/flags/code-refs.mjs` finds where your flags are used and posts the places to Venom Cloud,
which shows them on each flag and counts them in the stale-flags report. It needs Node 20 or later and nothing else.
It lists the project's flag keys (archived ones too), then looks for each key written as a quoted string literal
(`'key'`, `"key"` or `` `key` ``) in the repository's text files. It skips `.git`, `node_modules` and other dependency
and build directories, names the root `.gitignore` lists plainly, binary files and files over 1 MB, and keeps at most
50 references per flag. Each post replaces what that repository and branch had before.

Run it as a CI step on your main branch, with a Venom API key that may write flags:

```yaml
# .github/workflows/flag-refs.yml
on: { push: { branches: [main] } }
jobs:
  flag-refs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: >
          node tools/code-refs.mjs --base-url https://cloud.usevenom.dev --project default
          --repo "$GITHUB_REPOSITORY" --branch "$GITHUB_REF_NAME"
        env:
          VENOM_API_KEY: ${{ secrets.VENOM_API_KEY }}
```

`--dry-run` prints `path:line`, the flag and the line instead of posting; with `--flags a,b` it also skips the
download and needs no key. Other options: `--dir` (default `.`) and `--max-per-flag` (default 50).

## The REST API

Every path below is under `/flags/api/v1`. Answers are JSON; errors use the cloud's error shape
(`{"error": {"message", "type", "code"}}`). `{p}` is a project key (`default` unless you made others).

```bash
export VENOM=https://cloud.usevenom.dev
export AUTH="Authorization: Bearer $VENOM_API_KEY"
```

### Read

```bash
# who you are, your permissions, whether your org has the add-on, and the default project
curl -s "$VENOM/flags/api/v1/me" -H "$AUTH"

# flags, filtered: q, tag (repeatable), maintainer, status (active|archived|all), env + state (on|off), kind, limit, cursor
curl -s "$VENOM/flags/api/v1/projects/default/flags?env=production&state=on" -H "$AUTH"

# one flag, with every environment's targeting; the ETag header is its version
curl -si "$VENOM/flags/api/v1/projects/default/flags/new-checkout" -H "$AUTH"
```

### Create a flag

```bash
curl -s "$VENOM/flags/api/v1/projects/default/flags" -H "$AUTH" -H "content-type: application/json" \
  -d '{"key": "new-checkout", "name": "New checkout", "kind": "boolean", "tags": ["checkout"], "temporary": true}'
```

A boolean flag gets the variations `true` and `false`; pass `variations` for other kinds. A new flag is off in every
environment.

### Change a flag

Changes are a list of **instructions**, applied in order, all or none. Send the version you read in `If-Match`; if
the flag moved on since, the answer is `409 version_conflict` and nothing changes.

```bash
curl -s -X PATCH "$VENOM/flags/api/v1/projects/default/flags/new-checkout" -H "$AUTH" \
  -H "content-type: application/json" -H 'If-Match: "3"' -H "Idempotency-Key: rollout-2026-11-07" \
  -d '{
    "comment": "Roll out to 10% of users in production",
    "instructions": [
      { "kind": "turnFlagOn", "env": "production" },
      { "kind": "updateFallthrough", "env": "production",
        "serve": { "rollout": { "variations": [ { "variation": 0, "weight": 10000 }, { "variation": 1, "weight": 90000 } ] } } }
    ]
  }'
```

Rollout weights are in thousandths of a percent and add up to 100000. `"dryRun": true` validates and returns the diff
without saving; `POST …/flags/{key}/preview` with `{"instructions": […]}` does the same and also says which
environments would need approval. When an environment requires approval, the answer is `202` with the pending request.

The instructions:

| Scope | Instructions |
|---|---|
| The flag | `updateName`, `updateDescription`, `addTags`, `removeTags`, `updateMaintainer`, `updateTemporary`, `updateClientSide`, `addVariation`, `updateVariation`, `removeVariation`, `archive`, `restore` |
| One environment (`env`) | `turnFlagOn`, `turnFlagOff`, `updateOffVariation`, `updateFallthrough`, `addTargets`, `removeTargets`, `replaceTargets`, `addRule`, `removeRule`, `updateRuleServe`, `updateRuleDescription`, `reorderRules`, `addClauses`, `removeClauses`, `updateClause`, `addValuesToClause`, `removeValuesFromClause`, `replaceRules`, `addPrerequisite`, `updatePrerequisite`, `removePrerequisite`, `updateTrackEvents`, `copyEnvironment` |

Rules and conditions have ids, so `removeRule`, `updateClause` and the others name a rule by id, never by position.
For example, a rule that serves variation 0 to one plan:

```json
{ "kind": "addRule", "env": "staging", "description": "Pro plan",
  "clauses": [ { "contextKind": "user", "attribute": "plan", "op": "in", "values": ["pro"] } ],
  "serve": { "variation": 0 } }
```

### Everything else

| Path | Methods | What |
|---|---|---|
| `/projects`, `/projects/{p}` | GET, POST; GET, PATCH, DELETE | projects |
| `/projects/{p}/environments`, `…/environments/{env}` | POST; PATCH, DELETE | environments (name, colour, `requireApproval`, `confirmChanges`) |
| `…/environments/{env}/keys/{sdk\|mobile\|client}` | POST | rotate a key; the new one is in the answer, once |
| `/projects/{p}/flags`, `…/flags/{key}` | GET, POST; GET, PATCH, DELETE | flags |
| `…/flags/{key}/preview` | POST | a change's diff, without saving |
| `…/environments/{env}/segments`, `…/segments/{key}` | GET, POST; GET, PATCH, DELETE | segments (PATCH takes segment instructions such as `addIncluded`, `addRule`) |
| `…/environments/{env}/evaluate` | POST | `{ "context", "flags"? }`: what the context gets and why; never counted |
| `/projects/{p}/audit`, `…/audit/{id}` | GET | the history (`kind`, `key`, `env`, `actor`, `since`, `limit`, `cursor`) |
| `…/audit/{id}/revert` | POST | restore the resource as it was before that change (`{"force"?, "comment"?}`) |
| `/projects/{p}/approvals`, `…/approvals/{id}/{approve\|reject\|cancel\|apply}` | GET; POST | approval requests |
| `…/flags/{key}/schedule`, `/projects/{p}/scheduled/{id}` | GET, POST; DELETE | changes scheduled for later (`{"executeAt", "instructions", "comment"?}`) |
| `…/flags/{key}/insights?env=&hours=` | GET | evaluation counts per hour and variation |
| `/projects/{p}/stale?env=&days=` | GET | flags that look ready to remove, and why |
| `/projects/{p}/code-refs` | GET, POST | where flags are used in code; your CI posts `{repo, branch, refs}` |
| `/webhooks`, `/webhooks/{id}` | GET, POST; PATCH, DELETE | webhooks (admins) |

### Errors

| Status | Code | Means |
|---|---|---|
| 400 | `invalid_request` | the request is malformed |
| 401 | `invalid_api_key` | no credential, or a bad one |
| 403 | `forbidden`, `addon_required` | your role may not do this, or your org hasn't added Venom Flags |
| 404 | `not_found` | no such project, flag, segment or entry |
| 409 | `version_conflict` | the resource changed since the version you sent; the message has the current version |
| 422 | `invalid_instruction` | an instruction can't apply; the message names its index and why |
| 429 | `rate_limit_exceeded` | over 600 requests a minute for one credential |
