Skip to main content

​
API Reference

Superflag provides a REST API for fetching configs and managing flags programmatically.

​
Base URL

https://superflag.sh/api/v1

​
Authentication

Superflag uses different key types for different use cases:
Key TypePrefixUse CasePermissions
Publicpub_Client SDKs (browser, mobile)Read filtered config
SDKsdk_Server SDKsRead full config
CLIcli_CLI toolFull management access
Adminadmin_App management APIApp-level admin

​
Authorization Header

All API requests use Bearer token authentication: 
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_prod_..."

​
Endpoints

​
Client Endpoints

For fetching configs in your application:
EndpointMethodAuthDescription
/public-configGETpub_*Get filtered config for clients
/configGETsdk_*Get full config for servers

​
Management Endpoints

For managing flags, apps, and keys:
EndpointMethodAuthDescription
/appsGET, POSTcli_*List and create apps
/flagsGET, POST, PATCH, DELETEcli_*Manage flags
/keysGET, POST, PATCHcli_*Manage API keys

​
Response Format

All responses return JSON with this structure:

​
Success Response

{
  "data": { ... }
}

​
Error Response

{
  "error": "Error message"
}

​
Status Codes

CodeMeaning
200Success
201Created
304Not Modified (ETag match)
400Bad Request
401Unauthorized (invalid or missing key)
403Forbidden (key doesn’t have permission)
404Not Found
429Rate Limited (quota exceeded)
500Server Error

​
Rate Limiting

API requests are metered based on your plan:
  • Free: 25,000 requests/month/environment
  • Pro: 100,000 requests/month/environment
  • Enterprise: Custom limits
When you exceed your quota, you’ll receive a 429 status code. The SDKs will continue serving cached configs.

​
ETag Caching

The /public-config and /config endpoints support ETag-based caching to minimize bandwidth: First Request: 
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_..."

# Response includes ETag header
ETag: "v123"
Subsequent Request: 
curl https://superflag.sh/api/v1/public-config \
  -H "Authorization: Bearer pub_..." \
  -H "If-None-Match: \"v123\""

# If unchanged, returns 304 Not Modified (no body, minimal bandwidth)
# If changed, returns 200 with new config and updated ETag
This is how the SDKs achieve 90%+ bandwidth reduction.

​
CORS

The API supports CORS for browser-based requests: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, If-None-Match

​
Versioning

The API is versioned via URL path (/api/v1). Breaking changes will increment the version number (/api/v2). Current version: v1

​
SDKs

Official SDKs handle authentication, caching, and error handling for you:
  • React: @superflag-sh/react
  • React Native: @superflag-sh/react-native
  • CLI: @superflag-sh/cli

​
Next Steps

Public Config Endpoint

Fetch configs for client apps

Management Endpoints

Manage flags programmatically