openapi: 3.1.0
info:
  title: Flagsmith Admin Environments Identities 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: Identities
  description: Manage user identities within an environment. Identities represent individual users and their associated traits.
paths:
  /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
  /identities/:
    get:
      operationId: getIdentityFlags
      summary: Get flags and traits for an identity
      description: Retrieves all feature flags and traits for a specific user identity. The flags returned may differ from the environment defaults based on the identity's traits and segment membership. If the identity does not exist, it will be created. This endpoint also supports transient identities and traits that are used for evaluation but not persisted.
      tags:
      - Identities
      parameters:
      - $ref: '#/components/parameters/IdentifierQuery'
      - $ref: '#/components/parameters/TransientQuery'
      responses:
        '200':
          description: Successful response containing flags and traits for the identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponse'
        '400':
          description: Bad request - missing identifier parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing Environment Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: identifyUserAndGetFlags
      summary: Identify a user and get flags with traits
      description: Identifies a user by providing an identifier and optional traits in the request body. Returns the evaluated flags for that identity based on the provided traits and any existing traits. Traits provided in the request body are persisted for the identity unless marked as transient. This endpoint performs the entire SDK identity workflow in a single call.
      tags:
      - Identities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
      responses:
        '200':
          description: Successful response containing evaluated flags and persisted traits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponse'
        '400':
          description: Bad request - missing or invalid identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing Environment Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /traits/:
    post:
      operationId: setTraits
      summary: Set traits for an identity
      description: Sets one or more trait values for a given identity. If the identity does not exist, it will be created. Traits are key-value pairs associated with an identity that can be used for segment evaluation and personalized flag delivery.
      tags:
      - Identities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraitRequest'
      responses:
        '200':
          description: Successful response confirming the trait was set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trait'
        '400':
          description: Bad request - missing or invalid trait data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing Environment Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /traits/bulk/:
    put:
      operationId: setBulkTraits
      summary: Set multiple traits for an identity in bulk
      description: Sets multiple trait values for a given identity in a single API call. This is more efficient than making individual trait requests when updating multiple traits at once. If a trait value is set to null, the trait will be deleted.
      tags:
      - Identities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TraitRequest'
      responses:
        '200':
          description: Successful response confirming the traits were set
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Trait'
        '400':
          description: Bad request - missing or invalid trait data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing Environment Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TraitInput:
      type: object
      description: Input object for setting a trait value on an identity.
      required:
      - trait_key
      - trait_value
      properties:
        trait_key:
          type: string
          description: The key name of the trait to set
        trait_value:
          description: The value to set for the trait. Can be a string, integer, float, or boolean. Set to null to delete the trait.
          oneOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - type: 'null'
        transient:
          type: boolean
          description: When true, this trait is transient and will be used for evaluation but not persisted.
    IdentityRequest:
      type: object
      description: The request body for identifying a user and optionally setting traits.
      required:
      - identifier
      properties:
        identifier:
          type: string
          description: The unique identifier for the user identity in your application.
        traits:
          type: array
          description: An optional array of traits to set for this identity. Traits are used for segment evaluation and personalized flag delivery.
          items:
            $ref: '#/components/schemas/TraitInput'
        transient:
          type: boolean
          description: When true, the identity is transient and will not be persisted.
    TraitRequest:
      type: object
      description: Request body for setting a trait on an identity.
      required:
      - identity
      - trait_key
      - trait_value
      properties:
        identity:
          type: object
          description: The identity to set the trait on
          required:
          - identifier
          properties:
            identifier:
              type: string
              description: The unique identifier for the user identity
        trait_key:
          type: string
          description: The key name of the trait to set
        trait_value:
          description: The value to set for the trait. Set to null to delete the trait.
          oneOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - type: 'null'
    IdentityResponse:
      type: object
      description: The response object for an identity flags request, containing the evaluated flags and traits for the specified identity.
      properties:
        flags:
          type: array
          description: The evaluated feature flags for this identity
          items:
            $ref: '#/components/schemas/Flag'
        traits:
          type: array
          description: The traits associated with this identity
          items:
            $ref: '#/components/schemas/Trait'
    Trait:
      type: object
      description: A trait is a key-value pair associated with an identity, used for segment evaluation and personalization.
      properties:
        id:
          type: integer
          description: The unique identifier for this trait
        trait_key:
          type: string
          description: The key name of the trait
        trait_value:
          description: The value of the trait. Can be a string, integer, float, or boolean.
          oneOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
    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
    Identity:
      type: object
      description: A user identity within an environment, representing an individual user with their associated traits.
      properties:
        id:
          type: integer
          description: The unique identifier for this identity
        identifier:
          type: string
          description: The user-provided identifier for this identity
        environment:
          type: integer
          description: The ID of the environment this identity belongs to
    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
    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.
    Error:
      type: object
      description: An error response from the API
      properties:
        detail:
          type: string
          description: A human-readable error message
  parameters:
    TransientQuery:
      name: transient
      in: query
      description: When set to true, the identity is treated as transient and will not be persisted. The identity will be used for flag evaluation only.
      required: false
      schema:
        type: boolean
    IdentifierQuery:
      name: identifier
      in: query
      description: The unique identifier for the user identity. This is typically a user ID, email, or other unique string that identifies the user in your application.
      required: true
      schema:
        type: string
    EnvironmentApiKey:
      name: environment_api_key
      in: path
      description: The API key for the environment
      required: true
      schema:
        type: string
    IdentityId:
      name: identity_id
      in: path
      description: The unique identifier for the identity
      required: true
      schema:
        type: integer
  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