Documentation

Cloud API

Flipper Cloud API reference including features, gates, audits, and telemetry endpoints.

Overview

The Flipper Cloud API is available at https://www.flippercloud.io/adapter. It includes all of the open source Flipper API endpoints plus Cloud-specific endpoints for audits and telemetry.

Authentication

All requests require a token sent via the Flipper-Cloud-Token header:

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features

Tokens are scoped to a specific environment. You can create and manage tokens in your environment's settings. Tokens can be read-only or read-write depending on your needs.

Features

List All Features

GET /adapter/features

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features

{
  "features": [
    {
      "key": "search",
      "state": "on",
      "gates": [
        {"key": "boolean", "name": "boolean", "value": true},
        {"key": "expression", "name": "expression", "value": null},
        {"key": "groups", "name": "group", "value": []},
        {"key": "actors", "name": "actor", "value": []},
        {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
        {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
      ]
    }
  ]
}

Get a Feature

GET /adapter/features/{feature_name}

• feature_name - The name of the feature to retrieve

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/search

{
  "key": "search",
  "state": "on",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": true},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": []},
    {"key": "actors", "name": "actor", "value": []},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
  ]
}

Create a Feature

POST /adapter/features

• name - The name of the feature to create

curl -X POST -d "name=new_dashboard" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features

Returns an empty JSON response on success.

Delete a Feature

DELETE /adapter/features/{feature_name}

• feature_name - The name of the feature to delete

curl -X DELETE -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard

Successful deletion returns a 204 No Content response.

Clear a Feature

DELETE /adapter/features/{feature_name}/clear

• feature_name - The name of the feature to clear

curl -X DELETE -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/clear

Removes all gate values and returns a 204 No Content response.

Gates

All gate endpoints return a 200 HTTP status and the updated feature object on success.

Boolean

POST /adapter/features/{feature_name}/boolean - Enable for everyone

DELETE /adapter/features/{feature_name}/boolean - Disable

curl -X POST -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/boolean

{
  "key": "new_dashboard",
  "state": "on",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": true},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": []},
    {"key": "actors", "name": "actor", "value": []},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
  ]
}

Actors

POST /adapter/features/{feature_name}/actors - Enable for an actor

DELETE /adapter/features/{feature_name}/actors - Disable for an actor

• flipper_id - The identifier of the actor (e.g., User;123)

curl -X POST -d "flipper_id=User;123" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/actors

{
  "key": "new_dashboard",
  "state": "conditional",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": false},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": []},
    {"key": "actors", "name": "actor", "value": ["User;123"]},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
  ]
}

Groups

POST /adapter/features/{feature_name}/groups - Enable for a group

DELETE /adapter/features/{feature_name}/groups - Disable for a group

• name - The name of a registered group

curl -X POST -d "name=admins" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/groups

{
  "key": "new_dashboard",
  "state": "conditional",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": false},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": ["admins"]},
    {"key": "actors", "name": "actor", "value": []},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
  ]
}

Percentage of Actors

POST /adapter/features/{feature_name}/percentage_of_actors - Set percentage

DELETE /adapter/features/{feature_name}/percentage_of_actors - Clear percentage

• percentage - Integer between 0-100

curl -X POST -d "percentage=25" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/percentage_of_actors

{
  "key": "new_dashboard",
  "state": "conditional",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": false},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": []},
    {"key": "actors", "name": "actor", "value": []},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 25},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 0}
  ]
}

Percentage of Time

POST /adapter/features/{feature_name}/percentage_of_time - Set percentage

DELETE /adapter/features/{feature_name}/percentage_of_time - Clear percentage

• percentage - Integer between 0-100

curl -X POST -d "percentage=50" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  https://www.flippercloud.io/adapter/features/new_dashboard/percentage_of_time

{
  "key": "new_dashboard",
  "state": "conditional",
  "gates": [
    {"key": "boolean", "name": "boolean", "value": false},
    {"key": "expression", "name": "expression", "value": null},
    {"key": "groups", "name": "group", "value": []},
    {"key": "actors", "name": "actor", "value": []},
    {"key": "percentage_of_actors", "name": "percentage_of_actors", "value": 0},
    {"key": "percentage_of_time", "name": "percentage_of_time", "value": 50}
  ]
}

Actors

Check Features for an Actor

GET /adapter/actors/{flipper_id}

• keys - Comma-separated list of features to check (optional, returns all features if omitted)

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  "https://www.flippercloud.io/adapter/actors/User;123?keys=new_dashboard,search"

{
  "flipper_id": "User;123",
  "features": {
    "new_dashboard": {
      "enabled": true
    },
    "search": {
      "enabled": false
    }
  }
}

Audits

List Audits

GET /adapter/audits

• page - Page number (default: 1)
• per_page - Records per page (default: 100, max: 250)
• keys - Comma-separated feature keys to filter by

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  "https://www.flippercloud.io/adapter/audits?per_page=10"

{
  "audits": [
    {
      "action": "enable",
      "actor": {
        "type": "User",
        "id": "123"
      },
      "target": {
        "type": "Feature",
        "key": "new_dashboard"
      },
      "value": null,
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per": 10,
    "previous": null,
    "next": 2
  }
}

Audit actions include: enable, disable, enable_actor, disable_actor, enable_group, disable_group, percentage_of_actors, percentage_of_time, clear, create, remove, mirror, rollback, enable_expression, disable_expression.

Telemetry

Submit Telemetry

POST /adapter/telemetry

Submit feature flag evaluation metrics. This is typically handled automatically by the Flipper client gem.

curl -X POST \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "enabled_metrics": [
      {"key": "new_dashboard", "time": 1706108400, "result": true, "value": 150},
      {"key": "new_dashboard", "time": 1706108400, "result": false, "value": 50}
    ]
  }' \
  https://www.flippercloud.io/adapter/telemetry

Returns 202 Accepted with an empty JSON body.

Get Telemetry Summary

GET /adapter/telemetry/summary

• days - Number of days of history (clamped to your plan's retention limit)
• keys - Comma-separated feature keys to filter by

curl -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  "https://www.flippercloud.io/adapter/telemetry/summary?days=7"

{
  "days": 7,
  "resolution": "day",
  "features": [
    {
      "key": "new_dashboard",
      "summary": {
        "total": 10000,
        "enabled": 6000,
        "disabled": 4000,
        "enabled_rate": 0.6
      },
      "time_series": [
        {
          "timestamp": "2026-01-15T00:00:00Z",
          "total": 1500,
          "enabled": 900,
          "disabled": 600
        }
      ]
    }
  ]
}

Error Responses

Errors return JSON with a code and message:

{
  "code": 1,
  "message": "Feature not found",
  "more_info": "https://www.flippercloud.io/docs"
}

Common HTTP status codes:

• 401 - Invalid or missing token
• 402 - Feature requires a plan upgrade
• 403 - Token does not have write access
• 404 - Feature not found
• 422 - Invalid parameters