Flagsmith Flags API

openapi: 3.1.0
info:
  title: Flagsmith Admin Environments Flags API
  description: The Flagsmith Admin API allows developers to programmatically manage all aspects of their Flagsmith projects. Anything that can be done through the Flagsmith dashboard can also be accomplished via this API, including creating, updating, and deleting projects, environments, feature flags, segments, and users. It uses a secret Organisation API Token for authentication and provides a Swagger interface at api.flagsmith.com/api/v1/docs for interactive exploration.
  version: '1.0'
  contact:
    name: Flagsmith Support
    url: https://www.flagsmith.com/contact-us
  termsOfService: https://www.flagsmith.com/terms-of-service
servers:
- url: https://api.flagsmith.com/api/v1
  description: Flagsmith Production API
security:
- apiKeyAuth: []
tags:
- name: Flags
  description: Retrieve feature flags for an environment. Returns the current state of all feature flags including their enabled status and values.
paths:
  /flags/:
    get:
      operationId: listFlags
      summary: List all flags for an environment
      description: Retrieves all feature flags for the environment associated with the provided Environment Key. Returns an array of flag objects, each containing the feature definition, its enabled state, and any associated value. This endpoint is used by client-side SDKs to initialize flag state.
      tags:
      - Flags
      parameters:
      - $ref: '#/components/parameters/FeatureNameQuery'
      responses:
        '200':
          description: Successful response containing all flags for the environment
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flag'
        '401':
          description: Unauthorized - invalid or missing Environment Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    FeatureNameQuery:
      name: feature
      in: query
      description: Optional feature name to filter flags. When provided, returns only the flag matching the specified feature name.
      required: false
      schema:
        type: string
  schemas:
    Feature:
      type: object
      description: A feature definition containing metadata about the feature flag including its name, type, and default configuration.
      properties:
        id:
          type: integer
          description: The unique identifier for this feature
        name:
          type: string
          description: The name of the feature flag
        created_date:
          type: string
          format: date-time
          description: The date and time the feature was created
        description:
          type: string
          nullable: true
          description: A human-readable description of the feature
        initial_value:
          type: string
          nullable: true
          description: The initial value assigned to the feature when created
        default_enabled:
          type: boolean
          description: Whether the feature is enabled by default
        type:
          type: string
          enum:
          - STANDARD
          - MULTIVARIATE
          description: The type of feature flag. STANDARD for simple on/off flags, MULTIVARIATE for flags with multiple value variations.
    Flag:
      type: object
      description: A feature flag object containing the feature definition, its enabled state, and any associated value for the environment.
      properties:
        id:
          type: integer
          description: The unique identifier for this feature state
        feature:
          $ref: '#/components/schemas/Feature'
        feature_state_value:
          description: The value associated with this feature state. Can be a string, integer, boolean, or null depending on the feature configuration.
          oneOf:
          - type: string
          - type: integer
          - type: boolean
          - type: 'null'
        enabled:
          type: boolean
          description: Whether this feature flag is currently enabled
        environment:
          type: integer
          description: The ID of the environment this flag belongs to
        identity:
          type: integer
          nullable: true
          description: The identity ID if this is an identity-specific override, or null for environment defaults
        feature_segment:
          type: integer
          nullable: true
          description: The feature segment ID if this flag state is a segment override, or null otherwise
    Error:
      type: object
      description: An error response from the API
      properties:
        detail:
          type: string
          description: A human-readable error message
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: A secret Organisation API Token prefixed with 'Api-Key'. For example, 'Api-Key your-token-here'. This token should never be exposed in client-side code.
externalDocs:
  description: Flagsmith Admin API Documentation
  url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api