Venom Flags SDK and REST API
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.
Venom Flags 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, 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.
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 shutdownready(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 reasonCLIENT_NOT_READY.variation,boolVariation,stringVariation,numberVariation,jsonVariationreturn the value; the typed ones return the fallback when the value has another type.variationDetailadds the variation index and the reason (OFF,TARGET_MATCH,RULE_MATCHwith 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(defaulttrue;falsepolls),pollIntervalMs(default 30 s),eventsFlushMs(how often evaluation counts are sent, default 30 s;0never 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:
{ "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:
{ "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.
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(Falsepolls),poll_interval=30andevents_flush=30in seconds (0never sends counts),timeout=10per request,on_error. variation,bool_variation,string_variation,number_variation,json_variation,variation_detail,all_flags,flushandclosebehave as their TypeScript counterparts. The client is thread-safe and works as a context manager (with VenomFlags(…) as flags:).evaluate(flag, context, ruleset)andevaluate_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.
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, ReasonConfig:DisableStream(poll instead),PollIntervalandEventsFlush(default 30 s; a negativeEventsFlushnever sends counts),RequestTimeout(default 10 s),HTTPClient,OnError.Variation,BoolVariation,StringVariation,NumberVariation,JSONVariation,VariationDetail,AllFlags,OnUpdate,FlushandClose. Safe for concurrent use.venomflags.Evaluate(flag, ctx, ruleset)andEvaluateAllare 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 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:
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"}}'{ "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:
# .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).
export VENOM=https://cloud.usevenom.dev
export AUTH="Authorization: Bearer $VENOM_API_KEY"Read
# 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
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.
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:
{ "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 |