DocumentationREST APIAPI Reference

Getting Started

Quickstart

Run FlagForge locally, create a feature flag, and evaluate it from a TypeScript application

Quickstart

FlagForge separates flag management from application evaluation: use a server key to manage the control plane, then use a client key to bootstrap definitions into the TypeScript SDK. This quickstart uses the default SQLite database and the seeded demo project.

Prerequisites

  • Node.js 20 or newer

  • pnpm

  • curl

Install and start the API

The seed command prints a server key and a client key. In a second terminal, assign those values before making requests. With the default configuration, the seeded values are:

bash
SERVER_KEY="srv_dev_admin_key_change_me"
CLIENT_KEY="cli_demo_client_key"
BASE_URL="http://localhost:4000"
export FLAGFORGE_CLIENT_KEY="$CLIENT_KEY"

If you set ADMIN_SERVER_KEY, replace SERVER_KEY with that value. Keep the server key private; the client key is for SDK evaluation.

Quick start

1

Check liveness and database connectivity:

2
bash
curl "$BASE_URL/health"
3

Open http://localhost:4000/docs for the interactive Swagger UI, or fetch the generated contract from http://localhost:4000/openapi.json.

1

List projects with the server key and use the seeded demo project's ID in the next command:

2
bash
PROJECT_ID=$(curl -s "$BASE_URL/v1/projects" \
  -H "Authorization: Bearer $SERVER_KEY" | \
  node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).find(p=>p.key==="demo").id))')

curl -s -X POST "$BASE_URL/v1/projects/$PROJECT_ID/flags" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "name": "New checkout",
    "type": "boolean",
    "variations": [
      {"key": "on", "value": true},
      {"key": "off", "value": false}
    ]
  }'
3

Configure the flag for the seeded production environment:

4
bash
curl -s -X PUT "$BASE_URL/v1/projects/$PROJECT_ID/flags/new-checkout/targeting" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "enabled": true,
    "defaultVariationKey": "on",
    "offVariationKey": "off",
    "rules": []
  }'
1

In your application, install the SDK:

2
bash
pnpm add @flagforge/sdk
3

Initialize the client with the client key and evaluate the flag locally:

4
typescript
import { FlagForgeClient } from "@flagforge/sdk";

const client = new FlagForgeClient({
  clientKey: process.env.FLAGFORGE_CLIENT_KEY!,
  baseUrl: "http://localhost:4000",
  environment: "production",
});

await client.init();

const enabled = client.isEnabled("new-checkout", { key: "user-123" });
console.log(enabled);
5

init() fetches definitions from GET /v1/config; isEnabled then evaluates them in process without a network request for each check. Set FLAGFORGE_CLIENT_KEY to the client key assigned above before running your application.

What you should see

The health request succeeds, the API is available at http://localhost:4000, and the final program prints:

text
true

Next steps

Continue with FlagForge