launchdarkly Feature Flags API

openapi: 3.2.0
info:
  title: LaunchDarkly REST Feature Flags API
  description: The LaunchDarkly REST API provides programmatic access to the full LaunchDarkly feature management platform.
  version: '20240415'
  contact:
    name: LaunchDarkly Support
    url: https://support.launchdarkly.com
  termsOfService: https://launchdarkly.com/policies/terms-of-service
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://app.launchdarkly.com/api/v2
  description: LaunchDarkly Production API
security:
- bearerAuth: []
tags:
- name: Feature Flags
  description: Create, update, and manage feature flags and their targeting rules across projects and environments.
paths:
  /flags/{projectKey}:
    get:
      operationId: listFeatureFlags
      summary: List feature flags
      description: Returns a paginated list of all feature flags in the specified project. Supports filtering by tag, query string, and environment.
      tags:
      - Feature Flags
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      - name: env
        in: query
        description: Filter configurations by environment key.
        schema:
          type: string
      - name: tag
        in: query
        description: Filter flags by tag.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of flags to return.
        schema:
          type: integer
      - name: offset
        in: query
        description: Number of flags to skip for pagination.
        schema:
          type: integer
      - name: filter
        in: query
        description: A filter expression to apply to the flag list, supporting query, tags, and other fields.
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing a list of feature flags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureFlags'
        '401':
          description: Unauthorized. Invalid or missing access token.
        '404':
          description: Project not found.
    post:
      operationId: createFeatureFlag
      summary: Create a feature flag
      description: Creates a new feature flag in the specified project with the provided configuration including key, name, variations, and default targeting rules.
      tags:
      - Feature Flags
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureFlagBody'
      responses:
        '201':
          description: Feature flag created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureFlag'
        '400':
          description: Invalid request body.
        '401':
          description: Unauthorized. Invalid or missing access token.
        '409':
          description: A flag with the given key already exists.
  /flags/{projectKey}/{flagKey}:
    get:
      operationId: getFeatureFlag
      summary: Get a feature flag
      description: Returns a single feature flag by its key, including all environment-specific configurations and targeting rules.
      tags:
      - Feature Flags
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      - $ref: '#/components/parameters/FlagKey'
      - name: env
        in: query
        description: Filter configurations by environment key.
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the feature flag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureFlag'
        '401':
          description: Unauthorized. Invalid or missing access token.
        '404':
          description: Flag or project not found.
    patch:
      operationId: patchFeatureFlag
      summary: Update a feature flag
      description: Updates a feature flag using a JSON Patch or semantic patch representation. Supports modifying targeting rules, variations, prerequisites, and other flag settings.
      tags:
      - Feature Flags
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      - $ref: '#/components/parameters/FlagKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOperation'
      responses:
        '200':
          description: Feature flag updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureFlag'
        '400':
          description: Invalid patch request.
        '401':
          description: Unauthorized. Invalid or missing access token.
        '404':
          description: Flag or project not found.
        '409':
          description: Conflict due to concurrent modification.
    delete:
      operationId: deleteFeatureFlag
      summary: Delete a feature flag
      description: Permanently deletes a feature flag and all of its associated targeting rules and environment configurations.
      tags:
      - Feature Flags
      parameters:
      - $ref: '#/components/parameters/ProjectKey'
      - $ref: '#/components/parameters/FlagKey'
      responses:
        '204':
          description: Feature flag deleted successfully.
        '401':
          description: Unauthorized. Invalid or missing access token.
        '404':
          description: Flag or project not found.
components:
  schemas:
    Rollout:
      type: object
      description: A percentage rollout configuration.
      properties:
        variations:
          type: array
          description: The weighted variations in this rollout.
          items:
            type: object
            properties:
              variation:
                type: integer
                description: The variation index.
              weight:
                type: integer
                description: The rollout weight in thousandths of a percent (0-100000).
        bucketBy:
          type: string
          description: The context attribute used for bucketing.
        contextKind:
          type: string
          description: The context kind for rollout bucketing.
    FeatureFlag:
      type: object
      description: A feature flag with its configuration across all environments.
      properties:
        key:
          type: string
          description: The unique key identifying this feature flag.
        name:
          type: string
          description: The human-readable name of the feature flag.
        description:
          type: string
          description: A description of the feature flag purpose and behavior.
        kind:
          type: string
          description: The type of flag, such as boolean or multivariate.
          enum:
          - boolean
          - multivariate
        tags:
          type: array
          description: Tags applied to this feature flag.
          items:
            type: string
        creationDate:
          type: integer
          format: int64
          description: Unix epoch timestamp in milliseconds when the flag was created.
        variations:
          type: array
          description: The possible values this flag can serve.
          items:
            $ref: '#/components/schemas/Variation'
        temporary:
          type: boolean
          description: Whether this flag is intended to be temporary.
        archived:
          type: boolean
          description: Whether this flag has been archived.
        environments:
          type: object
          description: A map of environment keys to their flag configurations.
          additionalProperties:
            $ref: '#/components/schemas/FlagEnvironment'
        _links:
          $ref: '#/components/schemas/Links'
        _version:
          type: integer
          description: The current version number of this flag for concurrency control.
    Target:
      type: object
      description: An individual targeting entry for a specific variation.
      properties:
        values:
          type: array
          description: The list of context keys targeted.
          items:
            type: string
        variation:
          type: integer
          description: The variation index to serve to these targets.
        contextKind:
          type: string
          description: The context kind for this target.
    Clause:
      type: object
      description: A condition clause used in targeting rules.
      properties:
        attribute:
          type: string
          description: The context attribute to evaluate.
        op:
          type: string
          description: The comparison operator.
          enum:
          - in
          - endsWith
          - startsWith
          - matches
          - contains
          - lessThan
          - lessThanOrEqual
          - greaterThan
          - greaterThanOrEqual
          - before
          - after
          - segmentMatch
          - semVerEqual
          - semVerLessThan
          - semVerGreaterThan
        values:
          type: array
          description: The values to compare against.
          items: {}
        negate:
          type: boolean
          description: Whether to negate the clause.
        contextKind:
          type: string
          description: The context kind to evaluate.
    Rule:
      type: object
      description: A targeting rule with clauses and a variation or rollout.
      properties:
        _id:
          type: string
          description: The unique identifier for this rule.
        clauses:
          type: array
          description: The conditions that must be met for this rule to apply.
          items:
            $ref: '#/components/schemas/Clause'
        variation:
          type: integer
          description: The variation index to serve when this rule matches.
        rollout:
          $ref: '#/components/schemas/Rollout'
        trackEvents:
          type: boolean
          description: Whether to track events for this rule.
    FeatureFlags:
      type: object
      description: A paginated collection of feature flags.
      properties:
        items:
          type: array
          description: The list of feature flags.
          items:
            $ref: '#/components/schemas/FeatureFlag'
        totalCount:
          type: integer
          description: The total number of feature flags matching the query.
        _links:
          $ref: '#/components/schemas/Links'
    PatchOperation:
      type: object
      description: A JSON Patch or semantic patch request.
      properties:
        patch:
          type: array
          description: An array of JSON Patch operations.
          items:
            type: object
            required:
            - op
            - path
            properties:
              op:
                type: string
                description: The patch operation type.
                enum:
                - add
                - remove
                - replace
                - move
                - copy
                - test
              path:
                type: string
                description: The JSON Pointer path to the target field.
              value:
                description: The value to apply for add or replace operations.
        comment:
          type: string
          description: An optional comment describing the change.
    FlagEnvironment:
      type: object
      description: The configuration of a feature flag for a specific environment.
      properties:
        'on':
          type: boolean
          description: Whether the flag is currently enabled in this environment.
        archived:
          type: boolean
          description: Whether the flag is archived in this environment.
        salt:
          type: string
          description: The salt used for percentage rollout hashing.
        sel:
          type: string
          description: The selection identifier.
        lastModified:
          type: integer
          format: int64
          description: Unix epoch timestamp of the last modification.
        version:
          type: integer
          description: The version number of this flag configuration.
        targets:
          type: array
          description: Individual context targets for each variation.
          items:
            $ref: '#/components/schemas/Target'
        rules:
          type: array
          description: Targeting rules that determine which variation to serve.
          items:
            $ref: '#/components/schemas/Rule'
        fallthrough:
          type: object
          description: The default rule applied when no other rules match.
          properties:
            variation:
              type: integer
              description: The variation index to serve.
            rollout:
              $ref: '#/components/schemas/Rollout'
        offVariation:
          type: integer
          description: The variation index to serve when the flag is off.
    FeatureFlagBody:
      type: object
      description: The request body for creating a new feature flag.
      required:
      - name
      - key
      properties:
        name:
          type: string
          description: The human-readable name of the feature flag.
        key:
          type: string
          description: The unique key identifying this feature flag.
          pattern: ^[a-z0-9]([a-z0-9._-])*$
        description:
          type: string
          description: A description of the feature flag purpose.
        tags:
          type: array
          description: Tags to apply to the feature flag.
          items:
            type: string
        variations:
          type: array
          description: The variations this flag can serve.
          items:
            $ref: '#/components/schemas/Variation'
        temporary:
          type: boolean
          description: Whether this flag is intended to be temporary.
        clientSideAvailability:
          type: object
          description: Client-side SDK availability settings.
          properties:
            usingEnvironmentId:
              type: boolean
              description: Whether this flag is available to client-side SDKs using the environment ID.
            usingMobileKey:
              type: boolean
              description: Whether this flag is available to mobile SDKs.
        defaults:
          type: object
          description: Default variation settings for new environments.
          properties:
            onVariation:
              type: integer
              description: The index of the variation to serve when the flag is on.
            offVariation:
              type: integer
              description: The index of the variation to serve when the flag is off.
    Links:
      type: object
      description: HATEOAS links for navigating related resources.
      properties:
        self:
          type: object
          description: A link to this resource.
          properties:
            href:
              type: string
              description: The URL of this resource.
            type:
              type: string
              description: The media type.
      additionalProperties:
        type: object
        properties:
          href:
            type: string
            description: The URL of the linked resource.
          type:
            type: string
            description: The media type.
    Variation:
      type: object
      description: A single variation value that a feature flag can serve.
      properties:
        _id:
          type: string
          description: The unique identifier of this variation.
        value:
          description: The value of this variation. Can be any JSON type.
        name:
          type: string
          description: An optional human-readable name for this variation.
        description:
          type: string
          description: An optional description of this variation.
  parameters:
    FlagKey:
      name: flagKey
      in: path
      required: true
      description: The feature flag key identifying a specific flag.
      schema:
        type: string
        pattern: ^[a-z0-9]([a-z0-9._-])*$
    ProjectKey:
      name: projectKey
      in: path
      required: true
      description: The project key identifying a LaunchDarkly project.
      schema:
        type: string
        pattern: ^[a-z0-9]([a-z0-9-])*$
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: LaunchDarkly API access token. Create personal or service tokens in the LaunchDarkly dashboard under Account Settings.
externalDocs:
  description: LaunchDarkly API Documentation
  url: https://apidocs.launchdarkly.com/