Feature flags

Feature flags let you control how and when functionality is delivered to users by toggling behavior in your code without deploying changes.

A feature flag defines the flag key and its possible variants. A flag_environment stores that flag’s configuration for a specific environment (for example, prod, stage, test, or dev).

Flag attributes

Field	Type	Description
`id`	string	The UUID or `key` of the feature flag.
`key`	string	The flag name used to identify this feature flag in your codebase or SDK configuration. This name is unique within your workspace.
`summary`	string	Description of the feature flag, if defined.
`variants`	object	A list of named variants the flag can evaluate to. Each variant maps to a value used in your application. For boolean flags, variants include `"on": true` and `"off": false`.
`createdAt`	datetime (ISO 8601)	The date and time the feature flag was created.
`updatedAt`	datetime (ISO 8601)	The date and time the feature flag was last updated.

Flag relationships

Field	Type	Description
`slices`	array of objects	The flag’s per-environment configurations. Each item is a `flag_environment`.

flag_environment

Each flag_environment object represents a flag's configuration in one environment.

Field	Type	Description
`attributes.configuration`	string	The environment's current configuration: `on`, `off`, or `MIXED`).
`meta.environmentCode`	string	The environment associated with this configuration (for example, `prod`, `test`).

Think of a feature flag as the definition, and each flag_environment as its state in a particular environment.

Example: Get a feature flag

{
  "data": {
    "type": "flag",
    "id": "56338410-4aa2-417c-acf1-eda94d344c5f",
    "attributes": {
      "key": "improve_patch_loading_time23",
      "summary": "Reduces latency when switching patches by optimizing preload and memory handling routines.",
      "variants": {
        "on": true,
        "off": false
      },
      "createdAt": "2024-08-09T23:35:39Z",
      "updatedAt": "2025-07-14T23:08:59Z"
    },
    "relationships": {
      "slices": {
        "links": {
          "self": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f/environments"
        },
        "data": [
          {
            "type": "flag_environment",
            "id": "bc25a1cc-d41b-4d07-9b80-09b80b90199f"
          },
          {
            "type": "flag_environment",
            "id": "4b7885f4-5942-472a-855c-0dfe07702d00"
          },
          {
            "type": "flag_environment",
            "id": "5b213133-229b-4854-9fc3-86e1a0377cbe"
          },
          {
            "type": "flag_environment",
            "id": "94066897-46e2-4084-9b6f-cdeb8f28fa6f"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "flag_environment",
      "id": "bc25a1cc-d41b-4d07-9b80-09b80b90199f",
      "attributes": {
        "configuration": "off"
      },
      "relationships": {
        "flag": {
          "links": {
            "related": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f"
          },
          "data": {
            "type": "flag",
            "id": "56338410-4aa2-417c-acf1-eda94d344c5f"
          }
        }
      },
      "meta": {
        "environmentCode": "prod"
      }
    },
    {
      "type": "flag_environment",
      "id": "5b213133-229b-4854-9fc3-86e1a0377cbe",
      "attributes": {
        "configuration": "off"
      },
      "relationships": {
        "flag": {
          "links": {
            "related": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f"
          },
          "data": {
            "type": "flag",
            "id": "56338410-4aa2-417c-acf1-eda94d344c5f"
          }
        }
      },
      "meta": {
        "environmentCode": "test"
      }
    },
    {
      "type": "flag_environment",
      "id": "94066897-46e2-4084-9b6f-cdeb8f28fa6f",
      "attributes": {
        "configuration": "MIXED"
      },
      "relationships": {
        "flag": {
          "links": {
            "related": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f"
          },
          "data": {
            "type": "flag",
            "id": "56338410-4aa2-417c-acf1-eda94d344c5f"
          }
        }
      },
      "meta": {
        "environmentCode": "dev"
      }
    },
    {
      "type": "flag_environment",
      "id": "4b7885f4-5942-472a-855c-0dfe07702d00",
      "attributes": {
        "configuration": "off"
      },
      "relationships": {
        "flag": {
          "links": {
            "related": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f"
          },
          "data": {
            "type": "flag",
            "id": "56338410-4aa2-417c-acf1-eda94d344c5f"
          }
        }
      },
      "meta": {
        "environmentCode": "stage"
      }
    }
  ]
}

Example: Get a flag's environment configuration

{
  "data": {
    "type": "flag_environment",
    "id": "94066897-46e2-4084-9b6f-cdeb8f28fa6f",
    "attributes": {
      "configuration": "MIXED"
    },
    "relationships": {
      "flag": {
        "links": {
          "related": "/api/v1/flags/56338410-4aa2-417c-acf1-eda94d344c5f"
        },
        "data": {
          "type": "flag",
          "id": "56338410-4aa2-417c-acf1-eda94d344c5f"
        }
      }
    },
    "meta": {
      "environmentCode": "dev"
    }
  }
}

Example: Update a flag's environment configuration

To update the configuration of a flag in a specific environment, send a PATCH request to the flag's environment URL:

PATCH /api/v1/flags/{flag_key}/environments/{environment_id}

Replace:

{flag_key}: the flag name. For example, amazing_feature.
{environment_id}: the environment name. For example, prod (matches meta.environmentCode in responses).

Request body

{
  "data": {
    "type": "flag_environment",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "configuration": "on"
    }
  }
}

The URL path selects the flag and environment. The body only sets the new configuration. If your server requires id in the body, it must match the flag_environment id.