Flagsmith Admin API

openapi: 3.1.0
info:
  title: Flagsmith Admin 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
externalDocs:
  description: Flagsmith Admin API Documentation
  url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api
servers:
  - url: https://api.flagsmith.com/api/v1
    description: Flagsmith Production API
tags:
  - name: Environments
    description: >-
      Manage environments within a project. Environments represent deployment
      stages such as development, staging, and production.
  - name: Features
    description: >-
      Manage feature flags within a project. Features can be toggled on or off
      and can have remote configuration values.
  - name: Identities
    description: >-
      Manage user identities within an environment. Identities represent
      individual users and their associated traits.
  - name: Organisations
    description: >-
      Manage organisations within Flagsmith. Organisations are the top-level
      container for projects, users, and billing.
  - name: Projects
    description: >-
      Manage projects within an organisation. Projects contain environments
      and feature flags.
  - name: Segments
    description: >-
      Manage segments within a project. Segments define groups of users based
      on traits and rules for targeted flag delivery.
  - name: Users
    description: >-
      Manage organisation users and their permissions within Flagsmith.
  - name: Webhooks
    description: >-
      Configure webhooks for environments and organisations to receive
      notifications about flag changes and audit log events.
security:
  - apiKeyAuth: []
paths:
  /organisations/:
    get:
      operationId: listOrganisations
      summary: List organisations
      description: >-
        Retrieves a list of all organisations the authenticated user has
        access to. Returns organisation details including name, subscription
        information, and feature usage.
      tags:
        - Organisations
      responses:
        '200':
          description: Successful response containing a list of organisations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized - invalid or missing API token
  /organisations/{organisation_id}/:
    get:
      operationId: getOrganisation
      summary: Get an organisation
      description: >-
        Retrieves the details of a specific organisation by its ID, including
        the organisation name, subscription plan, and feature usage limits.
      tags:
        - Organisations
      parameters:
        - $ref: '#/components/parameters/OrganisationId'
      responses:
        '200':
          description: Successful response containing the organisation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organisation'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Organisation not found
  /projects/:
    get:
      operationId: listProjects
      summary: List projects
      description: >-
        Retrieves a list of all projects the authenticated user has access to
        across all organisations.
      tags:
        - Projects
      responses:
        '200':
          description: Successful response containing a list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing API token
    post:
      operationId: createProject
      summary: Create a project
      description: >-
        Creates a new project within an organisation. Projects are containers
        for environments and feature flags.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
  /projects/{project_id}/:
    get:
      operationId: getProject
      summary: Get a project
      description: >-
        Retrieves the details of a specific project by its ID, including its
        name, organisation, and associated environments.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response containing the project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
    put:
      operationId: updateProject
      summary: Update a project
      description: >-
        Updates the details of an existing project. Allows modification of the
        project name and other configurable properties.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: >-
        Permanently deletes a project and all associated environments, feature
        flags, and data. This action cannot be undone.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '204':
          description: Project deleted successfully
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
  /environments/:
    get:
      operationId: listEnvironments
      summary: List environments
      description: >-
        Retrieves a list of all environments the authenticated user has access
        to. Environments represent deployment stages within a project.
      tags:
        - Environments
      responses:
        '200':
          description: Successful response containing a list of environments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized - invalid or missing API token
  /environments/{environment_api_key}/:
    get:
      operationId: getEnvironment
      summary: Get an environment
      description: >-
        Retrieves the details of a specific environment by its API key,
        including its name, project, and feature states.
      tags:
        - Environments
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      responses:
        '200':
          description: Successful response containing the environment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Environment not found
    put:
      operationId: updateEnvironment
      summary: Update an environment
      description: >-
        Updates the details of an existing environment including its name,
        description, and configuration properties.
      tags:
        - Environments
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentInput'
      responses:
        '200':
          description: Environment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Environment not found
  /projects/{project_id}/features/:
    get:
      operationId: listFeatures
      summary: List features for a project
      description: >-
        Retrieves a list of all feature flags defined within a specific
        project. Returns feature metadata including name, type, description,
        and default values.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response containing a list of features
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
    post:
      operationId: createFeature
      summary: Create a feature flag
      description: >-
        Creates a new feature flag within a project. The feature will be
        created across all environments with the specified default values.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureInput'
      responses:
        '201':
          description: Feature created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminFeature'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
  /projects/{project_id}/features/{feature_id}/:
    get:
      operationId: getFeature
      summary: Get a feature flag
      description: >-
        Retrieves the details of a specific feature flag by its ID within a
        project, including its configuration and multivariate options.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FeatureId'
      responses:
        '200':
          description: Successful response containing the feature details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminFeature'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Feature or project not found
    put:
      operationId: updateFeature
      summary: Update a feature flag
      description: >-
        Updates the details of an existing feature flag including its name,
        description, type, and multivariate options.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FeatureId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureInput'
      responses:
        '200':
          description: Feature updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminFeature'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Feature or project not found
    delete:
      operationId: deleteFeature
      summary: Delete a feature flag
      description: >-
        Permanently deletes a feature flag from a project. This removes the
        feature from all environments. This action cannot be undone.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FeatureId'
      responses:
        '204':
          description: Feature deleted successfully
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Feature or project not found
  /environments/{environment_api_key}/featurestates/:
    get:
      operationId: listFeatureStates
      summary: List feature states for an environment
      description: >-
        Retrieves a list of all feature states within a specific environment.
        Feature states represent the enabled status and value of each feature
        flag within the environment.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      responses:
        '200':
          description: Successful response containing a list of feature states
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Environment not found
  /environments/{environment_api_key}/featurestates/{feature_state_id}/:
    patch:
      operationId: updateFeatureState
      summary: Update a feature state
      description: >-
        Updates the state of a feature flag within a specific environment.
        Allows toggling the enabled status and changing the feature value.
      tags:
        - Features
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
        - $ref: '#/components/parameters/FeatureStateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureStateInput'
      responses:
        '200':
          description: Feature state updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureState'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Feature state or environment not found
  /projects/{project_id}/segments/:
    get:
      operationId: listSegments
      summary: List segments for a project
      description: >-
        Retrieves a list of all segments defined within a specific project.
        Segments define groups of users based on trait-based rules for targeted
        flag delivery.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Successful response containing a list of segments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
    post:
      operationId: createSegment
      summary: Create a segment
      description: >-
        Creates a new segment within a project. Segments define groups of
        users based on trait-based rules and conditions for targeted feature
        flag delivery.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentInput'
      responses:
        '201':
          description: Segment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Project not found
  /projects/{project_id}/segments/{segment_id}/:
    get:
      operationId: getSegment
      summary: Get a segment
      description: >-
        Retrieves the details of a specific segment by its ID within a
        project, including its rules and conditions.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/SegmentId'
      responses:
        '200':
          description: Successful response containing the segment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Segment or project not found
    put:
      operationId: updateSegment
      summary: Update a segment
      description: >-
        Updates the details of an existing segment including its name,
        description, and rules.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/SegmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentInput'
      responses:
        '200':
          description: Segment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Segment or project not found
    delete:
      operationId: deleteSegment
      summary: Delete a segment
      description: >-
        Permanently deletes a segment from a project. Any segment overrides
        associated with this segment will also be removed. This action cannot
        be undone.
      tags:
        - Segments
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/SegmentId'
      responses:
        '204':
          description: Segment deleted successfully
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Segment or project not found
  /environments/{environment_api_key}/identities/:
    get:
      operationId: listIdentities
      summary: List identities for an environment
      description: >-
        Retrieves a paginated list of all user identities within a specific
        environment. Identities represent individual users with their
        associated traits and flag overrides.
      tags:
        - Identities
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      responses:
        '200':
          description: Successful response containing a list of identities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Environment not found
  /environments/{environment_api_key}/identities/{identity_id}/:
    get:
      operationId: getIdentity
      summary: Get an identity
      description: >-
        Retrieves the details of a specific identity by its ID within an
        environment, including its identifier and associated traits.
      tags:
        - Identities
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
        - $ref: '#/components/parameters/IdentityId'
      responses:
        '200':
          description: Successful response containing the identity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Identity or environment not found
    delete:
      operationId: deleteIdentity
      summary: Delete an identity
      description: >-
        Permanently deletes an identity and all associated traits and flag
        overrides from an environment. This action cannot be undone.
      tags:
        - Identities
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
        - $ref: '#/components/parameters/IdentityId'
      responses:
        '204':
          description: Identity deleted successfully
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Identity or environment not found
  /organisations/{organisation_id}/users/:
    get:
      operationId: listOrganisationUsers
      summary: List organisation users
      description: >-
        Retrieves a list of all users belonging to a specific organisation,
        including their roles and permissions.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/OrganisationId'
      responses:
        '200':
          description: Successful response containing a list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganisationUser'
        '401':
          description: Unauthorized - invalid or missing API token
        '404':
          description: Organisation not found
  /environments/{environment_api_key}/webhooks/:
    get:
      operationId: listEnvironmentWebhooks
      summary: List environment webhooks
      description: >-
        Retrieves a list of all webhooks configured for a specific
        environment. Environment webhooks receive flag evaluation data
        for identified users.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      responses:
        '200':
          description: Successful response containing a list of webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized - invalid or missing API token
    post:
      operationId: createEnvironmentWebhook
      summary: Create an environment webhook
      description: >-
        Creates a new webhook for an environment. The webhook will receive
        POST requests containing flag evaluation data whenever identities
        are evaluated.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/EnvironmentApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
  /organisations/{organisation_id}/webhooks/:
    get:
      operationId: listOrganisationWebhooks
      summary: List organisation webhooks
      description: >-
        Retrieves a list of all webhooks configured for a specific
        organisation. Organisation webhooks receive audit log events for
        changes made across the organisation.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/OrganisationId'
      responses:
        '200':
          description: Successful response containing a list of webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized - invalid or missing API token
    post:
      operationId: createOrganisationWebhook
      summary: Create an organisation webhook
      description: >-
        Creates a new webhook for an organisation. The webhook will receive
        POST requests containing audit log events for changes made across
        the organisation.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/OrganisationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad request - validation error
        '401':
          description: Unauthorized - invalid or missing API token
components:
  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.
  parameters:
    OrganisationId:
      name: organisation_id
      in: path
      description: The unique identifier for the organisation
      required: true
      schema:
        type: integer
    ProjectId:
      name: project_id
      in: path
      description: The unique identifier for the project
      required: true
      schema:
        type: integer
    EnvironmentApiKey:
      name: environment_api_key
      in: path
      description: The API key for the environment
      required: true
      schema:
        type: string
    FeatureId:
      name: feature_id
      in: path
      description: The unique identifier for the feature
      required: true
      schema:
        type: integer
    FeatureStateId:
      name: feature_state_id
      in: path
      description: The unique identifier for the feature state
      required: true
      schema:
        type: integer
    SegmentId:
      name: segment_id
      in: path
      description: The unique identifier for the segment
      required: true
      schema:
        type: integer
    IdentityId:
      name: identity_id
      in: path
      description: The unique identifier for the identity
      required: true
      schema:
        type: integer
  schemas:
    PaginatedResponse:
      type: object
      description: >-
        A paginated response wrapper containing the results count and
        navigation links.
      properties:
        count:
          type: integer
          description: The total number of results
        next:
          type: string
          nullable: true
          format: uri
          description: URL to the next page of results
        previous:
          type: string
          nullable: true
          format: uri
          description: URL to the previous page of results
        results:
          type: array
          description: The array of result objects for this page
          items:
            type: object
    Organisation:
      type: object
      description: >-
        An organisation in Flagsmith, the top-level container for projects,
        users, and billing.
      properties:
        id:
          type: integer
          description: The unique identifier for this organisation
        name:
          type: string
          description: The name of the organisation
        created_date:
          type: string
          format: date-time
          description: When the organisation was created
        webhook_notification_email:
          type: string
          nullable: true
          description: Email address for webhook failure notifications
        num_seats:
          type: integer
          description: Number of available seats in the organisation
        persist_trait_data:
          type: boolean
          description: Whether trait data is persisted for identities
    Project:
      type: object
      description: >-
        A project in Flagsmith, containing environments and feature flag
        definitions.
      properties:
        id:
          type: integer
          description: The unique identifier for this project
        name:
          type: string
          description: The name of the project
        created_date:
          type: string
          format: date-time
          description: When the project was created
        organisation:
          type: integer
          description: The ID of the organisation this project belongs to
        hide_disabled_flags:
          type: boolean
          description: Whether to hide disabled flags from SDK responses
        enable_realtime_updates:
          type: boolean
          description: Whether real-time flag updates are enabled
    ProjectInput:
      type: object
      description: Input object for creating or updating a project
      required:
        - name
        - organisation
      properties:
        name:
          type: string
          description: The name of the project
          maxLength: 2000
        organisation:
          type: integer
          description: The ID of the organisation to create the project in
    Environment:
      type: object
      description: >-
        An environment in Flagsmith representing a deployment stage such as
        development, staging, or production.
      properties:
        id:
          type: integer
          description: The unique identifier for this environment
        name:
          type: string
          description: The name of the environment
        api_key:
          type: string
          description: The client-side API key for this environment
        description:
          type: string
          nullable: true
          description: A description of the environment
        project:
          type: integer
          description: The ID of the project this environment belongs to
        minimum_change_request_approvals:
          type: integer
          nullable: true
          description: >-
            Minimum number of approvals required for change requests in this
            environment
        allow_client_traits:
          type: boolean
          description: Whether client-side SDKs can set traits
        hide_sensitive_data:
          type: boolean
          description: Whether sensitive data is hidden in the dashboard
    EnvironmentInput:
      type: object
      description: Input object for updating an environment
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the environment
        description:
          type: string
          nullable: true
          description: A description of the environment
        allow_client_traits:
          type: boolean
          description: Whether client-side SDKs can set traits
        hide_sensitive_data:
          type: boolean
          description: Whether se

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flagsmith/refs/heads/main/openapi/flagsmith-admin-api-openapi.yml