> ## 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
> Manage apps, flags, and keys programmatically
# 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_*`):
```bash theme={null}
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:**
```json theme={null}
{
"data": [
{
"id": "app_abc123",
"name": "my-app",
"createdAt": "2025-01-01T00:00:00Z"
}
]
}
```
### Create App
```
POST /api/v1/apps
```
**Request Body:**
```json theme={null}
{
"name": "my-new-app"
}
```
**Response:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"data": {
"dark-mode": {
"type": "bool",
"value": true
},
"api-url": {
"type": "string",
"value": "https://api.example.com"
}
}
}
```
### Create Flag
```
POST /api/v1/flags
```
**Request Body:**
```json theme={null}
{
"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:**
```json theme={null}
{
"data": {
"version": 43,
"flag": {
"type": "bool",
"value": true
}
}
}
```
### Update Flag
```
PATCH /api/v1/flags
```
**Request Body:**
```json theme={null}
{
"appId": "app_abc123",
"env": "production",
"key": "dark-mode",
"value": false
}
```
**Response:**
```json theme={null}
{
"data": {
"version": 44,
"flag": {
"type": "bool",
"value": false
}
}
}
```
### Delete Flag
```
DELETE /api/v1/flags?appId=app_abc123&env=production&key=old-feature
```
**Response:**
```json theme={null}
{
"data": {
"version": 45
}
}
```
## API Keys
### List Keys
```
GET /api/v1/keys?appId=app_abc123&env=production
```
**Response:**
```json theme={null}
{
"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:**
```json theme={null}
{
"appId": "app_abc123",
"env": "production",
"type": "pub"
}
```
**Key Types:**
* `pub` - Public client key (for browsers/mobile, read-only)
* `sdk` - Server key (for backend)
**Response:**
```json theme={null}
{
"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:**
```json theme={null}
{
"data": {
"success": true
}
}
```
## Bulk Operations
### Bulk Update Flags
```
POST /api/v1/flags/bulk
```
**Request Body:**
```json theme={null}
{
"appId": "app_abc123",
"env": "production",
"flags": {
"feature-a": true,
"feature-b": false,
"api-timeout": 30
}
}
```
**Response:**
```json theme={null}
{
"data": {
"version": 46,
"updated": 3
}
}
```
## Examples
### Create App and Flag (JavaScript)
```javascript theme={null}
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)
```bash theme={null}
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)
```python theme={null}
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
```json theme={null}
{
"error": "Not authenticated"
}
```
### 403 Forbidden
```json theme={null}
{
"error": "Insufficient permissions"
}
```
### 404 Not Found
```json theme={null}
{
"error": "App not found"
}
```
### 400 Bad Request
```json theme={null}
{
"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](/cli/commands) is easier than calling the API directly:
```bash theme={null}
superflag apps create my-new-app
superflag use my-new-app production
superflag flags create --key dark-mode --type bool --value true
```
## Next Steps
Authentication and general info
Use the CLI instead of API