Coming soon! A Pro version of the Flipper gem for entirely local installations.

Get Updates

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.

Token access levels

  • Read Only tokens can evaluate features but cannot change them. Use Read Only for production applications and any client that only needs to evaluate flags.
  • Read/Write tokens can evaluate and change features. Use Read/Write for personal, development, and test environments where the application or automation needs to change flags.

Manage preview environments is a separate permission from the access level. It lets a stable token create preview environments and delete the environments it created, but does not grant permission to change features. Enable it on a dedicated read-only preview automation token in a stable custom environment such as previews, rather than on a production application token.

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

Features belong to the project, so deleting a feature removes it from every environment. This endpoint requires a writable Production environment token. Requests using other environment tokens return 403 Forbidden; you can also delete the feature in Flipper Cloud.

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}
  ]
}

Expression

POST /adapter/features/{feature_name}/expression - Set an expression

DELETE /adapter/features/{feature_name}/expression - Clear the expression

Send the expression as a JSON request body. Every Any and All group must
contain at least one condition. To remove every condition, use DELETE instead
of posting an empty group. Empty groups return HTTP 422 with the
expression_invalid error.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Flipper-Cloud-Token: YOUR_TOKEN" \
  -d '{"All":[{"Equal":[{"Property":["plan"]},{"String":["pro"]}]}]}' \
  https://www.flippercloud.io/adapter/features/new_dashboard/expression

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
    }
  }
}

Environments

Create and delete custom environments for the project your token belongs to. These endpoints are intended for temporary preview environments, such as pull request or branch previews.

Only custom environments are affected. Production and personal environments are never created or deleted by these endpoints. Creating an environment counts against your plan's custom environment limit.

Use two tokens for preview environments:

  1. Create a dedicated stable custom environment such as previews. In it, create a read-only token named something like Preview Environments with Manage preview environments enabled. Use it to create and delete preview environments. Avoid using a production application token for preview automation.
  2. Use the token returned by the create endpoint inside the preview app itself.

The returned preview app token cannot create more environments. Keep it available until teardown because it can delete its own environment if the preview automation token has been rotated or disabled.

Create an Environment

POST /adapter/environments

  • name - The name of the environment to create (required). Names that generate reserved slugs like new, edit, or admin are rejected.
curl -X POST -d "name=pr-1234" \
  -H "Flipper-Cloud-Token: PREVIEW_ENVIRONMENT_MANAGER_TOKEN" \
  https://www.flippercloud.io/adapter/environments

{
  "environment": {
    "id": 42,
    "slug": "pr-1234",
    "name": "pr-1234",
    "state": "other",
    "created_at": "2026-01-15T12:00:00Z"
  },
  "token": {
    "name": "API",
    "access": "read_and_write",
    "value": "Mb72kngHcVSLGefYptt2JvX5"
  }
}

The response includes a read-write token scoped to the new environment. Use its value as the Flipper-Cloud-Token for that preview app.

You can safely call create more than once with the same token and name. If the environment already exists and was created by that token, Flipper Cloud returns it instead of creating a duplicate. Existing matching environments return 200; newly created environments return 201. If another token or the web dashboard created the environment with that name, the request returns 409 with an environment_name_taken code. If your plan's custom environment limit has been reached, the request returns 402 with a custom_environments_limit code.

Create errors

Status Code Meaning
402 custom_environments_limit The project has reached its plan's custom environment limit.
403 preview_environment_management_token_required The token cannot manage preview environments. Preview app tokens never have this capability.
403 organization_membership The token owner no longer has the organization access required for this project.
403 project_membership The token owner no longer has access to this project.
409 environment_name_taken The name belongs to an environment not created by this token.
422 name_missing The request did not include a usable name.
422 name_invalid The name cannot produce a valid, non-reserved slug.
422 token_limit Flipper Cloud could not create a returned token because the environment reached its active token limit.

Delete an Environment

DELETE /adapter/environments/{id}

  • id - The environment ID returned by create.
curl -X DELETE \
  -H "Flipper-Cloud-Token: PREVIEW_ENVIRONMENT_MANAGER_TOKEN" \
  "https://www.flippercloud.io/adapter/environments/42"

Deletes the custom environment, including its tokens, gates, and audits. Authenticate with the preview-environment management token that created it. The returned preview app token can also delete its own environment. Other tokens receive 403 with a not_environment_creator code.

Deleting an environment that is already gone, or is not a custom environment, returns 204. Successful deletion also returns 204 No Content. Repeated calls with the creating preview-environment management token are safe, and the ID remains the same if the environment is renamed in the dashboard.

Delete errors

Status Code Meaning
403 not_environment_creator The token is neither the environment's creator token nor its returned preview token.
403 organization_membership The token owner no longer has the organization access required for this project.
403 project_membership The token owner no longer has access to this project.
422 environment_id_required The path did not include a valid positive environment ID.

Audits

List Audits

GET /adapter/audits

Audit history is available on paid plans. Free-plan responses preserve the same
response shape, but return an empty audits array and a limits object with
"limited": true and "max_events": 0.

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

page, per_page, and keys must be scalar, valid UTF-8 query parameters. Invalid numeric values, container-shaped values, conflicting Rack shapes, and malformed encodings return a JSON 400 or 422 response.

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
  },
  "limits": {
    "limited": false
  }
}

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.

The endpoint accepts the content types supported by existing clients and gzip-compressed request bodies. Gzip requests are limited to 256 KiB compressed and 1 MiB after expansion. Malformed JSON, non-object JSON, invalid encodings, decompression errors, and size-limit violations return JSON 400 or 422 responses before telemetry is queued.

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

days and keys must be scalar, valid UTF-8 query parameters. Invalid numeric values, container-shaped values, conflicting Rack shapes, and malformed encodings return a JSON 400 or 422 response.

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

{
  "days": 7,
  "resolution": "day",
  "features": [
    {
      "key": "new_dashboard",
      "description": "New dashboard experience for pro users",
      "longevity": "temporary",
      "tags": ["growth", "billing"],
      "creator": {
        "id": 42,
        "name": "Ada Lovelace",
        "email": "[email protected]"
      },
      "owner": {
        "id": 57,
        "name": "Grace Hopper",
        "email": "[email protected]"
      },
      "created_at": "2025-09-15T10:30:00Z",
      "state": "conditional",
      "gates_summary": {
        "boolean": false,
        "actors": 3,
        "groups": 2,
        "percentage_of_actors": 25,
        "percentage_of_time": 0,
        "expression": true
      },
      "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
        }
      ]
    }
  ]
}

Each feature includes configuration context alongside telemetry data:

  • description — Feature description, or null if not set
  • longevity — "temporary", "permanent", or null if not set
  • tags — Array of tag strings (empty array if none)
  • creator — User who created the feature, or null if unknown. Object with id, name, and email.
  • owner — User assigned as the feature's owner, or null if unassigned. Object with id, name, and email.
  • created_at — When the feature was created (ISO 8601)
  • state — Current state: "on", "conditional", or "off"
  • gates_summary — Summary of gate configuration (always present):
    • boolean — Whether the boolean gate is enabled
    • actors — Number of individually enabled actors
    • groups — Number of enabled groups
    • percentage_of_actors — Percentage of actors enabled (0-100)
    • percentage_of_time — Percentage of time enabled (0-100)
    • expression — Whether an expression gate is active

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

Error Code Reference

  • 7 - The expression is invalid. Empty Any and All groups are not
    accepted; use DELETE /adapter/features/{feature_name}/expression to clear
    an expression.
Ready to try it out?

Get audit history, rollbacks, advanced permissions, analytics, and all of your projects in one place.

Try It Out
Prefer our Cloudless option?

You can choose from several tiers to sponsor Flipper on GitHub and get some great benefits!

Sponsor Flipper
Product
Documentation
Reference
Cloud
Adapters

The Friday Deploy

Get updates for all things Flipper—open source and cloud.

Have questions? Need help?

Email us any time or head on over to our documentation or status page for the latest on the app or API.

Ready to take Flipper for a swim?

No credit card required. 14-day free trial. And customer support directly from the developers.

Flipper Cloud Back to Top