REST API

Complete API reference for managing feature flags programmatically. All endpoints use JSON and require authentication.

Base URL

https://api.rollgate.io

Authentication

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

See Authentication for details on key types.

SDK Endpoints

These endpoints are used by the SDKs to fetch flag values.

GET/api/v1/sdk/flagsClient or Server key

Fetch all flags for the current project. Supports conditional requests with ETag.

Query Parameters

user_id - Optional user ID for targeting

Response

{
  "flags": {
    "new-checkout": true,
    "dark-mode": false,
    "beta-features": true
  }
}

POST/api/v1/sdk/evaluateClient or Server key

Evaluate a single flag by key. Useful for server-side evaluation, scripts, and one-shot requests without an SDK.

Query Parameters

key - Required. The flag key to evaluate

Request Body (optional)

{
  "user": {
    "id": "user-123",
    "attributes": {
      "plan": "pro",
      "country": "IT"
    }
  }
}

Response

{
  "key": "new-checkout",
  "value": true,
  "variation": "enabled",
  "reason": "targeting_match"
}

GET/api/v1/sdk/streamClient or Server key

SSE endpoint for real-time flag updates. Returns event stream with flag changes.

Headers

Accept: text/event-stream

Event Format

event: flags
data: {"flags":{"new-checkout":true}}

event: heartbeat
data: {"timestamp":1704672000}

Management Endpoints

These endpoints require a server API key and are used to manage flags.

GET/api/v1/flagsServer key

List all flags in the project with their settings.

Response

{
  "flags": [
    {
      "id": "clx...",
      "key": "new-checkout",
      "name": "New Checkout Flow",
      "enabled": true,
      "description": "Enables the new checkout experience",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z"
    }
  ]
}

POST/api/v1/flagsServer key

Create a new feature flag.

Request Body

{
  "key": "new-feature",
  "name": "New Feature",
  "description": "Optional description",
  "enabled": false
}

PUT/api/v1/flags/:idServer key

Update a flag's settings.

Request Body

{
  "enabled": true,
  "name": "Updated Name"
}

DELETE/api/v1/flags/:idServer key

Delete a flag permanently.

Warning: This action cannot be undone. The flag will be immediately removed from all SDK responses.

Targeting Rules

Target users based on their attributes (country, plan, email, app version, etc.). Rules are evaluated server-side for security - you just need to send the user context.

GET/api/v1/operatorsClient or Server key

Get all available operators for building targeting rules. Returns operator name, description, and expected value type.

Response

{
  "operators": [
    {
      "name": "equals",
      "description": "Exact match (case-insensitive)",
      "category": "string",
      "example": "country equals \"IT\""
    },
    {
      "name": "contains",
      "description": "String contains value",
      "category": "string",
      "example": "email contains \"@company\""
    },
    {
      "name": "in",
      "description": "Value in comma-separated list",
      "category": "list",
      "example": "plan in \"pro,growth\""
    },
    {
      "name": "semver_gt",
      "description": "Semantic version greater than",
      "category": "semver",
      "example": "app_version semver_gt \"2.0.0\""
    }
    // ... 18 operators total
  ]
}

This endpoint is cached for 24 hours. Use it to populate dropdown menus in your rule builder UI.

Sending User Context

To evaluate targeting rules, the SDK must send user attributes. There are multiple ways to do this:

Method 1: X-User-Context Header (Recommended)

Send all user attributes as a JSON object (base64-encoded or plain JSON):

cURL

curl https://api.rollgate.io/api/v1/sdk/flags \
  -H "Authorization: Bearer rg_client_your_key" \
  -H "X-User-Context: eyJpZCI6InVzZXItMTIzIiwiZW1haWwiOiJqb2huQGNvbXBhbnkuY29tIiwiY291bnRyeSI6IklUIiwicGxhbiI6InBybyJ9"

# Decoded: {"id":"user-123","email":"[email protected]","country":"IT","plan":"pro"}

Method 2: Individual Headers

For simpler cases, use individual headers:

cURL

curl https://api.rollgate.io/api/v1/sdk/flags \
  -H "Authorization: Bearer rg_client_your_key" \
  -H "X-User-ID: user-123" \
  -H "X-User-Email: [email protected]" \
  -H "X-User-Attributes: country=IT,plan=pro"

Method 3: POST with Body

Use POST to send user context in the request body:

cURL

curl -X POST https://api.rollgate.io/api/v1/sdk/flags \
  -H "Authorization: Bearer rg_client_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "email": "[email protected]",
    "country": "IT",
    "plan": "pro",
    "app_version": "2.1.0"
  }'

Security note: User context is used only for targeting evaluation. It is not stored or logged. For sensitive attributes, consider hashing them before sending.

Scheduled Changes

Schedule flag changes to happen automatically at a specific time. Perfect for timed releases, promotional campaigns, and maintenance windows.

Common Use Cases

• Product launch: Enable a new feature at exactly 9 AM on launch day
• Flash sale: Show promotional banner for 48 hours, then auto-disable
• Maintenance: Disable payments API integration during provider maintenance

POST/api/v1/flags/:flagId/environments/:envId/scheduleServer key

Schedule a flag to be enabled or disabled at a specific time.

Request Body

{
  "enable_at": "2026-01-15T09:00:00Z",
  "disable_at": "2026-01-20T18:00:00Z"
}

Both fields are optional. Set only enable_at for a one-time enable, or both for a temporary feature window.

Example: Schedule a 3-Day Sale

cURL

curl -X POST https://api.rollgate.io/api/v1/flags/abc123/environments/prod/schedule \
  -H "Authorization: Bearer rg_server_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_at": "2026-02-14T00:00:00Z",
    "disable_at": "2026-02-17T00:00:00Z"
  }'

Valentine's Day sale: auto-enables Feb 14 at midnight, auto-disables Feb 17.

DELETE/api/v1/flags/:flagId/environments/:envId/scheduleServer key

Clear any scheduled changes for a flag. Use this if plans change and you need to cancel a scheduled enable/disable.

Rollback & History

Every flag change is automatically saved to history. When things go wrong, rollback instantly to the previous state - no need to remember what the settings were.

When to Use Rollback

• Broken feature: Enabled a flag and now errors are spiking? Rollback in seconds.
• Accidental change: Someone toggled the wrong flag? Instantly restore previous state.
• Audit trail: Need to know who changed what and when? Check the history.

GET/api/v1/flags/:flagId/environments/:envId/historyServer key

Get the change history for a flag (last 20 changes). Each entry includes the full state at that point in time.

Response

{
  "history": [
    {
      "id": "abc123",
      "enabled": true,
      "rollout_percentage": 100,
      "changed_at": "2026-01-07T15:30:00Z",
      "changed_by": "user-id",
      "change_type": "manual"
    },
    {
      "id": "xyz789",
      "enabled": false,
      "rollout_percentage": 50,
      "changed_at": "2026-01-07T14:00:00Z",
      "changed_by": "user-id",
      "change_type": "rollback"
    }
  ]
}

change_type can be: manual (user toggle),scheduled (auto-change), or rollback.

POST/api/v1/flags/:flagId/environments/:envId/rollbackServer key

Rollback a flag to its previous state. Instantly reverts the last change, restoring enabled state, rollout percentage, and targeting rules.

Response

{
  "message": "Rollback successful",
  "enabled": false,
  "rollout_percentage": 50,
  "rolled_back_to": "2026-01-07T14:00:00Z"
}

Example: Emergency Rollback After Bad Deploy

You enabled new-payment-flow and checkout errors spiked. One command to fix it:

cURL

curl -X POST https://api.rollgate.io/api/v1/flags/abc123/environments/prod/rollback \
  -H "Authorization: Bearer rg_server_your_key"

The flag instantly reverts. Errors stop. Your team can debug without pressure.

Usage Limits

Limits are enforced per organization based on your plan:

Plan	Requests/month	SSE Connections	Projects
Free	500K	1	3
Starter	1M	25	5
Pro	3M	100	10
Growth	12M	500	Unlimited

When limits are exceeded, the API returns 429 Too Many Requests. All plans include unlimited flags.

Error Responses

All errors return a consistent JSON structure:

{
  "error": {
    "code": "AUTH_001",
    "category": "AUTH",
    "message": "Invalid API key",
    "status": 401
  }
}

Code	Status	Description
AUTH_001	401	Invalid or missing API key
AUTH_002	403	Insufficient permissions
RATE_001	429	Rate limit exceeded
NOT_FOUND_001	404	Resource not found