Control points

A control point is a named decision the product can change without a deploy. Your application asks Fireweave for a typed value — boolean, string, number, or object — and uses that value to choose a path. The wire, Decision envelopes, conformance fixtures, and capabilities.features.flags still say flagKey. The product name is control point. Do not invent controlPointKey.

Why it exists

Operators reason about a release decision, not “a boolean in a flag console.” Evaluation is still a typed getter so call sites stay small. The nine methods are identical across all seven languages. A language missing any of them fails conformance/surface/.

When to use it

Use a control point whenever your process must choose a value that Fireweave (or a test fixture) owns:

Gate a new code path (getBooleanValue)
Pick a string variant, numeric threshold, or JSON payload
Inspect a full Decision with a *Details method when you need reason or error fields

Do not use an in-app helper named fw.isOn. That symbol is not in the SDK.

How it relates

Concept	Relation
`flagKey`	Parameter name on evaluate, Decision, and `POST /v1/flags/evaluate`
Targeting	The same `targetingKey` selects which value you get
Adapters	Remote, local, or in-memory resolve the value
OpenFeature	The bundled provider was retired. This page is the evaluation API

The nine methods

Every SDK exposes the surface under a namespace named controlPoints, cased for the language: controlPoints (Node, Web, Java, Swift), control_points (Python, Rust), ControlPoints (Go). flags / Flags() is a deprecated alias pointing at the same object. Do not use it in new examples. It is silent at runtime except in Python (one DeprecationWarning per process).

Method	Returns
`getBooleanValue(key, default, context?)`	`boolean`
`getStringValue(key, default, context?)`	`string`
`getNumberValue(key, default, context?)`	`number` — number, not integer. `Decision.value` is `jsonValue`
`getObjectValue(key, default, context?)`	JSON
`getBooleanDetails(key, default, context?)`	`Decision`
`getStringDetails(key, default, context?)`	`Decision`
`getNumberDetails(key, default, context?)`	`Decision`
`getObjectDetails(key, default, context?)`	`Decision`
`evaluate(key, type, default, context?, options?)`	`Decision` — the general form the eight delegate to

*Value returns Decision.value. *Details returns the whole Decision. Both take the same arguments, so you upgrade from one to the other without restructuring the call. Naming follows each language’s idiom (get_boolean_value, GetBooleanValue) but the method set and its semantics do not vary. Python still accepts get_integer_value as a deprecated alias of get_number_value. It logs one DeprecationWarning per process the first time you call it.

Sync vs async

Language	Read
Node	`async` — getters return a `Promise`
Web, Swift	Synchronous — a cache read. Safe inside a render / UI path
Python, Go, Java, Rust	Blocking / synchronous

Web and Swift prefetch during initFireweave / identify. A hung prefetch does not block boot. The runtime enters STALE and serves your default with reason STALE. See Lifecycle.

Return discipline

A control-point read never throws. Every failure resolves to your default with a Decision naming the reason.

Situation	`value`	`reason`	`error.kind`
Decision served	resolved	`TARGETING_MATCH` \| `SPLIT` \| `STATIC` \| `CACHED`	—
Key unknown (remote)	`default`	`ERROR`	`FlagNotFound`
Key unknown (local)	`default`	`DEFAULT`	—
Resolved value is the wrong type	`default`	`ERROR`	`TypeMismatch`
`default` does not match `type`	`default`	`ERROR`	`TypeMismatch`
Context fails validation	`default`	`ERROR`	`InvalidContext`
Runtime not initialised	`default`	`ERROR`	`NotReady`
Runtime closed	`default`	`ERROR`	`AlreadyClosed`
Backend unreachable / slow	`default`	`ERROR`	`Network` \| `Timeout` \| `BackendUnavailable`
Prefetch ceiling lost the race (web / Swift)	`default`	`STALE`	—

STALE is a reason, not an error. The runtime is serving a usable-but-not-fresh cache. Init is the exception: bad configuration fails loudly at boot. See Configuration. A v1 read is side-effect free. No read emits telemetry as a consequence of being called.

Validation, before any I/O

Implementations validate in this order and stop at the first failure:

key — non-empty, ≤256 characters, no control characters
default vs type — getBooleanValue with a non-boolean default is TypeMismatch
context — depth, key count, value size, reserved keys
lifecycle — not NotReady, not AlreadyClosed

The Decision

Field	Meaning
`flagKey`	The key you asked for
`value`	Resolved value, or your default on failure
`variant`	Multivariate variant name, when present
`reason`	Why this value was chosen
Error fields	Kind / code / safe message — on error Decisions

SPLIT is a Decision reason, not a ramp controller. The SDK does not advance percentages.

What it looks like

import { initFireweave } from '@fireweaveai/server-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl: process.env.FW_API_URL!,
  apiKey: process.env.FW_PROJECT_API_KEY!,
});

const on = await fireweave.controlPoints.getBooleanValue(
  'new-checkout',
  false,
  { targetingKey: 'user_42' },
);

const decision = await fireweave.controlPoints.getBooleanDetails(
  'new-checkout',
  false,
  { targetingKey: 'user_42' },
);
// decision.value, decision.reason — never throws

Reads are synchronous.

import { initFireweave } from '@fireweaveai/web-sdk';

const fireweave = await initFireweave({
  mode: 'remote',
  apiKey: PUBLIC_FW_PROJECT_API_KEY,
  apiUrl: PUBLIC_FW_API_URL,
  context: { targetingKey: 'anonymous' },
});

const on = fireweave.controlPoints.getBooleanValue('new-checkout', false);

from fireweave import EvaluationContext, init_fireweave

client = init_fireweave(
    mode="remote",
    api_key="project-api-key_...",
    api_url="https://app-server.fireweave.ai",
)

on = client.control_points.get_boolean_value(
    "new-checkout", False, EvaluationContext("user_42")
)
decision = client.control_points.get_boolean_details(
    "new-checkout", False, EvaluationContext("user_42")
)

client, err := fireweave.Init(fireweave.Options{
    Mode:   fireweave.ModeRemote,
    APIKey: "project-api-key_…",
    APIURL: "https://app-server.fireweave.ai",
})
// handle err — Init fails loudly

evalCtx := fireweave.NewEvaluationContext("user_42", nil)
on := client.ControlPoints().GetBooleanValue("new-checkout", false, &evalCtx)
decision := client.ControlPoints().GetBooleanDetails("new-checkout", false, &evalCtx)

The nine methods do not take a context.Context. Internally they use context.Background(). The remote adapter’s request timeout bounds the HTTP call.

FireweaveClient client = Fireweave.init(InitOptions.remote(
    System.getenv("FW_PROJECT_API_KEY"),
    System.getenv("FW_API_URL")));

boolean on = client.controlPoints().getBooleanValue(
    "new-checkout",
    false,
    EvaluationContext.builder().targetingKey("user_42").build());

Classes live under ai.fireweave.sdk.{domain,application,infrastructure.adapters}. There is no facade re-export package.

use fireweave::{init_fireweave, EvaluationContext, InitOptions};

let client = init_fireweave(InitOptions::remote(
    "project-api-key_...",
    "https://app-server.fireweave.ai",
)).unwrap();

let ctx = EvaluationContext::new().with_targeting_key("user_42");
let enabled = client.control_points.get_boolean_value("new-checkout", false, Some(&ctx));

Reads are synchronous, same shape as the web SDK.

import Fireweave

let client = try await initFireweave(.local(InitFireweaveLocalOptions(
    controlPoints: ["new-checkout": true]
)))
let on = client.controlPoints.getBooleanValue("new-checkout", default: false)
await client.shutdown()

Call-site defaults stay false (or the safe production fallback). Do not write getBooleanValue(key, true) to dogfood locally — that same true is the production fallback when a control point is absent.

Targeting — identity on every evaluate
Adapters — who resolves the value
Errors — the 15-kind taxonomy
Node, Python, Go, Java, Web, Rust

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Why it exists

When to use it

How it relates

The nine methods

Sync vs async

Return discipline

Validation, before any I/O

The Decision

What it looks like

​Why it exists

​When to use it

​How it relates

​The nine methods

​Sync vs async

​Return discipline

​Validation, before any I/O

​The Decision

​What it looks like

​Related

Why it exists

When to use it

How it relates

The nine methods

Sync vs async

Return discipline

Validation, before any I/O

The Decision

What it looks like

Related