Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Management API

The management API allows you to create and manage apps, flags, environments, and API keys programmatically.

​
Authentication

Management endpoints require a CLI token (cli_*): 
curl https://superflag.sh/api/v1/apps \
  -H "Authorization: Bearer cli_..."
Get a CLI token by running superflag login and copying from ~/.superflag/credentials.json.

​
Apps

​
List Apps

GET /api/v1/apps
Response: 
{
  "data": [
    {
      "id": "app_abc123",
      "name": "my-app",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

​
Create App

POST /api/v1/apps
Request Body: 
{
  "name": "my-new-app"
}
Response: 
{
  "data": {
    "id": "app_xyz789",
    "name": "my-new-app",
    "createdAt": "2025-01-06T12:00:00Z"
  }
}

​
Environments

Environments are created automatically with each app:
  • development
  • staging
  • production

​
List Environments

GET /api/v1/envs?appId=app_abc123
Response: 
{
  "data": [
    {
      "id": "env_dev123",
      "name": "development",
      "appId": "app_abc123"
    },
    {
      "id": "env_stg123",
      "name": "staging",
      "appId": "app_abc123"
    },
    {
      "id": "env_prd123",
      "name": "production",
      "appId": "app_abc123"
    }
  ]
}

​
Flags

​
List Flags

GET /api/v1/flags?appId=app_abc123&env=production
Response: 
{
  "data": {
    "dark-mode": {
      "type": "bool",
      "value": true
    },
    "api-url": {
      "type": "string",
      "value": "https://api.example.com"
    }
  }
}

​
Create Flag

POST /api/v1/flags
Request Body: 
{
  "appId": "app_abc123",
  "env": "production",
  "key": "new-feature",
  "type": "bool",
  "value": true
}
Flag Types:
  • bool - Boolean values (true/false)
  • string - Text values
  • number - Numeric values
  • json - JSON objects
Response: 
{
  "data": {
    "version": 43,
    "flag": {
      "type": "bool",
      "value": true
    }
  }
}

​
Update Flag

PATCH /api/v1/flags
Request Body: 
{
  "appId": "app_abc123",
  "env": "production",
  "key": "dark-mode",
  "value": false
}
Response: 
{
  "data": {
    "version": 44,
    "flag": {
      "type": "bool",
      "value": false
    }
  }
}

​
Delete Flag

DELETE /api/v1/flags?appId=app_abc123&env=production&key=old-feature
Response: 
{
  "data": {
    "version": 45
  }
}

​
API Keys

​
List Keys

GET /api/v1/keys?appId=app_abc123&env=production
Response: 
{
  "data": [
    {
      "id": "key_123",
      "type": "pub",
      "prefix": "pub_prod_",
      "createdAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": "key_456",
      "type": "sdk",
      "prefix": "sdk_prod_",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

​
Create Key

POST /api/v1/keys
Request Body: 
{
  "appId": "app_abc123",
  "env": "production",
  "type": "pub"
}
Key Types:
  • pub - Public client key (for browsers/mobile, read-only)
  • sdk - Server key (for backend)
Response: 
{
  "data": {
    "id": "key_789",
    "type": "pub",
    "key": "pub_prod_abc123xyz789...",
    "createdAt": "2025-01-06T12:00:00Z"
  }
}
The full key is only returned once when created. Store it securely.

​
Revoke Key

DELETE /api/v1/keys?keyId=key_789
Response: 
{
  "data": {
    "success": true
  }
}

​
Bulk Operations

​
Bulk Update Flags

POST /api/v1/flags/bulk
Request Body: 
{
  "appId": "app_abc123",
  "env": "production",
  "flags": {
    "feature-a": true,
    "feature-b": false,
    "api-timeout": 30
  }
}
Response: 
{
  "data": {
    "version": 46,
    "updated": 3
  }
}

​
Examples

​
Create App and Flag (JavaScript)

const token = 'cli_...'

// Create app
const appResponse = await fetch('https://superflag.sh/api/v1/apps', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'my-new-app' })
})

const { data: app } = await appResponse.json()

// Create flag
const flagResponse = await fetch('https://superflag.sh/api/v1/flags', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appId: app.id,
    env: 'production',
    key: 'dark-mode',
    type: 'bool',
    value: true
  })
})

const { data: flag } = await flagResponse.json()
console.log('Created flag at version:', flag.version)

​
Update Flag (Curl)

curl -X PATCH https://superflag.sh/api/v1/flags \
  -H "Authorization: Bearer cli_..." \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "app_abc123",
    "env": "production",
    "key": "dark-mode",
    "value": false
  }'

​
Create API Key (Python)

import requests

token = 'cli_...'

response = requests.post(
    'https://superflag.sh/api/v1/keys',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'appId': 'app_abc123',
        'env': 'production',
        'type': 'pub'
    }
)

data = response.json()
print('New key:', data['data']['key'])

​
Error Responses

​
401 Unauthorized

{
  "error": "Not authenticated"
}

​
403 Forbidden

{
  "error": "Insufficient permissions"
}

​
404 Not Found

{
  "error": "App not found"
}

​
400 Bad Request

{
  "error": "Invalid flag type"
}

​
Rate Limits

Management endpoints share the same rate limits as config endpoints:
  • 25,000 requests/month/environment (Free)
  • 100,000 requests/month/environment (Pro)

​
CLI Alternative

For most use cases, the CLI is easier than calling the API directly: 
superflag apps create my-new-app
superflag use my-new-app production
superflag flags create --key dark-mode --type bool --value true

​
Next Steps

API Overview

Authentication and general info

CLI Reference

Use the CLI instead of API