API Reference

The FeatureFlags API uses REST conventions. All requests must include your environment API key in the Authorization header.

Authentication

Authorization: Bearer ff_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://api.featureflags.dev/v1

Get All Flags

Fetch all flag configurations for the authenticated environment. This is the primary endpoint used by the Laravel package for syncing.

GET /api/flags

Response

{
  "data": [
    {
      "key": "new-checkout",
      "name": "New Checkout Flow",
      "type": "boolean",
      "enabled": true,
      "default_value": false,
      "rollout_percentage": 25,
      "rules": [
        {
          "priority": 1,
          "conditions": [
            {"trait": "plan", "operator": "equals", "value": "pro"}
          ],
          "value": true
        }
      ]
    },
    {
      "key": "api-version",
      "name": "API Version",
      "type": "string",
      "enabled": true,
      "default_value": "v1",
      "rollout_percentage": null,
      "rules": []
    }
  ]
}

Submit Telemetry

Send evaluation events for analytics tracking. Events are batched by the Laravel package.

POST /api/telemetry

Request Body

{
  "events": [
    {
      "flag_key": "new-checkout",
      "context_id": "user_123",
      "value": true,
      "timestamp": "2025-11-29T14:30:00Z"
    },
    {
      "flag_key": "api-version",
      "context_id": "user_456",
      "value": "v2",
      "timestamp": "2025-11-29T14:30:01Z"
    }
  ]
}

Response

{
  "received": true,
  "count": 2
}

Management API

The following endpoints require Sanctum authentication (used by the dashboard, not the Laravel package).

Projects

GET    /api/projects           # List all projects
POST   /api/projects           # Create a project
GET    /api/projects/{id}      # Get a project
PATCH  /api/projects/{id}      # Update a project
DELETE /api/projects/{id}      # Delete a project

Environments

GET    /api/projects/{id}/environments        # List environments
POST   /api/projects/{id}/environments        # Create environment
PATCH  /api/environments/{id}                 # Update environment
DELETE /api/environments/{id}                 # Delete environment
POST   /api/environments/{id}/regenerate-key  # Regenerate API key

Flags

GET    /api/projects/{id}/flags  # List flags in project
POST   /api/projects/{id}/flags  # Create a flag
GET    /api/flags/{id}           # Get a flag
PATCH  /api/flags/{id}           # Update a flag
DELETE /api/flags/{id}           # Delete a flag

Flag Environment Config

GET   /api/flags/{id}/environments/{env_id}  # Get flag config for environment
PATCH /api/flags/{id}/environments/{env_id}  # Update flag config

Update Flag Config

PATCH /api/flags/{flag_id}/environments/{environment_id}

{
  "enabled": true,
  "default_value": false,
  "rollout_percentage": 50,
  "rules": [
    {
      "priority": 1,
      "conditions": [
        {"trait": "plan", "operator": "equals", "value": "pro"}
      ],
      "value": true
    }
  ]
}

Error Responses

// 401 Unauthorized
{
  "message": "Unauthenticated."
}

// 403 Forbidden
{
  "message": "This action is unauthorized."
}

// 404 Not Found
{
  "message": "Resource not found."
}

// 422 Validation Error
{
  "message": "The given data was invalid.",
  "errors": {
    "key": ["The key field is required."]
  }
}

// 429 Rate Limit (MAU exceeded)
{
  "received": false,
  "error": "mau_limit_exceeded",
  "message": "Monthly active user limit exceeded."
}

Rate Limits

Next Steps

• Webhooks - Get notified of flag changes