API Reference

Flipswitch provides two main APIs:

Admin API

Manage projects, flags, environments, and users

Flag API (OFREP)

Evaluate feature flags using the OpenFeature protocol

Authentication

Admin API

The Admin API uses JWT Bearer tokens for authentication:

curl https://api.flipswitch.dev/api/admin/projects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

To obtain a token, authenticate via the /api/v1/auth/login endpoint or through the dashboard.

Flag API

The Flag API uses API keys via the X-API-Key header:

curl -X POST https://api.flipswitch.dev/ofrep/v1/evaluate/flags/dark-mode \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"context": {"targetingKey": "user-123"}}'

API keys are generated per-environment in the dashboard.

Base URLs

Environment	URL
Production	`https://api.flipswitch.dev`
Self-hosted	Your configured server URL

Rate Limits

API	Limit
Admin API	1000 requests/minute
Flag API	10000 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid flag key format",
    "details": {
      "field": "key",
      "constraint": "must be kebab-case"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Malformed request or validation error
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists
`RATE_LIMITED`	429	Rate limit exceeded
`INTERNAL_ERROR`	500	Server error

API Reference

Admin API

Flag API (OFREP)

On this page