API Overview

The Flagify REST API lets you manage flags, environments, and targeting rules programmatically. All SDK operations are backed by this API.

Base URL

https://api.flagify.dev/v1

Authentication

All API requests require an API key passed via the X-API-Key header:

curl https://api.flagify.dev/v1/flags \
  -H "X-API-Key: sk_prod_AbC12xYz_your-secret-key"

API key format

Flagify API keys follow a structured format:

{type}_{environment}_{keyId}_{secret}

Segment	Values	Description
`type`	`pk`, `sk`	`pk` = publishable (client-side), `sk` = secret (server-side)
`environment`	`dev`, `staging`, `prod`	The environment this key is scoped to
`keyId`	random string	Unique key identifier
`secret`	random string	Cryptographic secret

Examples:

sk_prod_AbC12xYz_dGhpcyBpcyBhIHNlY3JldA     # secret key, production
pk_dev_XyZ98aBc_Y2xpZW50LXNpZGUta2V5         # publishable key, development

Flag endpoints

Method	Path	Description	Key type
`GET`	`/v1/flags`	List all flags in the project	`sk`
`POST`	`/v1/flags`	Create a new flag	`sk`
`GET`	`/v1/flags/:key`	Get a specific flag	`sk`
`PATCH`	`/v1/flags/:key`	Update a flag	`sk`
`DELETE`	`/v1/flags/:key`	Delete a flag	`sk`

Evaluation endpoints

Used by the SDKs. These are the only endpoints a publishable (pk_*) key can call.

Method	Path	Description	Key type
`GET`	`/v1/eval/flags`	Fetch all flags for the environment bound to the key	`pk` or `sk`
`GET`	`/v1/eval/flags/:key`	Fetch a single flag	`pk` or `sk`
`POST`	`/v1/eval/flags/evaluate`	Evaluate all flags for a user context (batch, used by SDK sync)	`pk` or `sk`
`POST`	`/v1/eval/flags/:key/evaluate`	Evaluate a single flag for a user context	`pk` or `sk`
`GET`	`/v1/eval/stream`	SSE stream of flag changes	`pk` or `sk`

Segment & targeting endpoints

Segments are reusable user groups; targeting rules bind flags to segments or inline conditions per environment.

Method	Path	Description	Key type
`GET`	`/v1/projects/:projectId/segments`	List segments in a project	`sk`
`POST`	`/v1/projects/:projectId/segments`	Create a segment	`sk`
`DELETE`	`/v1/segments/:id`	Delete a segment	`sk`
`GET`	`/v1/flag-environments/:flagEnvId/targeting`	List targeting rules for a flag in one environment	`sk`
`PUT`	`/v1/flag-environments/:flagEnvId/targeting`	Replace all targeting rules for a flag in one environment	`sk`

Environment & API key endpoints

Method	Path	Description	Key type
`GET`	`/v1/environments`	List environments	`sk`
`GET`	`/v1/environments/:id/api-keys`	List API keys for an environment	`sk`
`POST`	`/v1/environments/:id/api-keys`	Generate a new API key pair	`sk`
`POST`	`/v1/environments/:id/api-keys/rotate`	Rotate API keys	`sk`
`POST`	`/v1/environments/:id/api-keys/revoke`	Revoke all active API keys for an environment	`sk`

Audit log endpoints

Every write (flag create/toggle, key generation, membership change, billing action, …) is recorded in a workspace-scoped audit log.

Method	Path	Description	Key type
`GET`	`/v1/workspaces/:wid/audit`	List audit events (paginated)	`sk`

Query parameters:

Param	Description
`cursor`	Opaque pagination cursor from a previous response
`limit`	Page size (default `50`)
`action`	Filter by action name (e.g. `flag.toggled`, `key.generated`)
`resourceType`	Filter by resource type (e.g. `flag`, `apikey`, `membership`)
`actorUserId`	Filter by the user who performed the action
`projectId`	Filter to events that belong to a single project

Billing endpoints

Workspace-scoped billing operations. All require owner/admin role on the workspace.

Method	Path	Description	Key type
`GET`	`/v1/workspaces/:wid/billing`	Get current plan, usage, and Stripe status	`sk`
`POST`	`/v1/workspaces/:wid/billing/checkout`	Create a Stripe Checkout session for a plan upgrade	`sk`
`POST`	`/v1/workspaces/:wid/billing/portal`	Create a Stripe Customer Portal session	`sk`
`POST`	`/v1/workspaces/:wid/billing/preview-change`	Preview the proration for a plan change	`sk`
`POST`	`/v1/workspaces/:wid/billing/change-plan`	Apply a plan change (upgrade/downgrade)	`sk`
`POST`	`/v1/workspaces/:wid/billing/apply-retention-discount`	Apply a retention discount during a cancellation flow	`sk`
`POST`	`/v1/workspaces/:wid/billing/downgrade-feedback`	Record feedback captured during a downgrade	`sk`
`POST`	`/v1/webhooks/stripe`	Stripe webhook receiver (signed by Stripe — not called directly)	none

Request format

All request bodies use JSON. Set the Content-Type header:

curl -X POST https://api.flagify.dev/v1/flags \
  -H "X-API-Key: sk_prod_AbC12xYz_your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-feature",
    "type": "boolean",
    "description": "Enable the new feature"
  }'

Response format

All responses return JSON with a consistent structure:

{
  "data": {
    "key": "new-feature",
    "type": "boolean",
    "enabled": false,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Errors follow the same structure:

{
  "error": {
    "code": "not_found",
    "message": "Flag 'nonexistent' not found"
  }
}

Rate limits

Plan	Requests per minute
Free	60
Pro	600
Enterprise	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1705312800