Skip to content
Docs menu

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.

View .md

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

{ "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 (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.

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