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. Developers can create, update, and manage feature flags, targeting rules, user segments, projects, environments, and team members. The API also supports scheduled flag changes, release pipelines, experimentation, approval workflows, and webhook integrations. Authentication is handled via personal or service access tokens, and the API follows a versioned scheme with the current default version being 20240415.
  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:
    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.
    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.
    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:
        true:
          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.
    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'
    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.
    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.
    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.
    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.
    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.
    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.
  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/