LaunchDarkly Releases (beta) API

openapi: 3.2.0
info:
  title: LaunchDarkly REST Releases (beta) API
  description: 'This documentation describes LaunchDarkly''s REST API. To access the complete OpenAPI spec directly, use Get OpenAPI spec. To learn how to use LaunchDarkly using the user interface (UI) instead, read our product documentation. ## Authentication


    LaunchDarkly''s REST API uses the HTTPS protocol with a minimum TLS version of 1.2. All REST API resources are authenticated with either personal or service access tokens, or session cookies. Other authentication mechanisms are not supported. You can manage personal access tokens on your **Authorization** page in the LaunchDarkly UI. LaunchDarkly also has SDK keys, mobile keys, and client-side IDs that are used by our server-side SDKs, mobile SDKs, and JavaScript-based SDKs, respectively. **These keys cannot be used to access our REST API**. These keys are environment-specific, and can only perform read-only operations such as fetching feature flag settings. | Auth mechanism | Allowed resources | Use cases |

    | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- |

    | Personal or service access tokens | Can be customized on a per-token basis | Building scripts, custom integrations, data export. |

    | SDK keys | Can only access read-only resources specific to server-side SDKs. Restricted to a single environment. | Server-side SDKs |

    | Mobile keys | Can only access read-only resources specific to mobile SDKs, and only for flags marked available to mobile keys. Restricted to a single environment. | Mobile SDKs |

    | Client-side ID | Can only access read-only resources specific to JavaScript-based client-side SDKs, and only for flags marked available to client-side. Restricted to a single environment. | Client-side JavaScript |


    > #### Keep your access tokens and SDK keys private

    >

    > Access tokens should _never_ be exposed in untrusted contexts. Never put an access token in client-side JavaScript, or embed it in a mobile application. LaunchDarkly has special mobile keys that you can embed in mobile apps. If you accidentally expose an access token or SDK key, you can reset it from your **Authorization** page. >

    > The client-side ID is safe to embed in untrusted contexts. It''s designed for use in client-side JavaScript. ### Authentication using request header


    The preferred way to authenticate with the API is by adding an `Authorization` header containing your access token to your requests. The value of the `Authorization` header must be your access token. Manage personal access tokens from the **Authorization** page. ### Authentication using session cookie


    For testing purposes, you can make API calls directly from your web browser. If you are logged in to the LaunchDarkly application, the API will use your existing session to authenticate calls. Depending on the permissions granted as part of your role, you may not have permission to perform some API calls. You will receive a `401` response code in that case. > ### Modifying the Origin header causes an error

    >

    > LaunchDarkly validates that the Origin header for any API request authenticated by a session cookie matches the expected Origin header. The expected Origin header is `https://app.launchdarkly.com`. >

    > If the Origin header does not match what''s expected, LaunchDarkly returns an error. This error can prevent the LaunchDarkly app from working correctly. >

    > Any browser extension that intentionally changes the Origin header can cause this problem. For example, Cross-Origin Resource Sharing (CORS) extensions used during development can modify the Origin header and cause the app to fail. >

    > To prevent this error, do not modify your Origin header. >

    > LaunchDarkly does not require origin matching when authenticating with an access token, so this issue does not affect normal API usage.'
  contact:
    name: LaunchDarkly Technical Support Team
    url: https://support.launchdarkly.com
    email: support@launchdarkly.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2.0'
servers:
- url: https://app.launchdarkly.com
  description: ' Default'
- url: https://app.launchdarkly.us
  description: ' Federal'
security:
- ApiKey:
  - read
  - write
tags:
- name: Releases (beta)
  description: '> ### This feature is in beta

    >

    > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read Beta resources.

    >

    > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible.


    Release pipelines standardize and automate the release process for feature flags across a series of phases, where each phase consists of one or more environments and audiences. When you add a flag to an existing release pipeline, you create a "release" to automate that flag''s progress through the pipeline.


    Use the releases API to add a flag to an existing release pipeline, or to monitor or update an ongoing release for a flag. Updating an ongoing release generally involves the following steps:


    1. Obtain the release phases associated with the release. The `phases` field provides an ordered list of all pipeline phases associated with the flag''s release. `phases` is returned in the response when you Create a new release for a flag or Get the release for a flag.


    2. Determine the `_id` of the phase you want to start. Release pipeline phases take place in their configured order, so find the first incomplete, unstarted phase in the `phases` list. For example, in a newly-created release the first phase in the `phases` list has both the `complete` and `started` fields set to `false`.


    3. Use the phase `_id` value with the Update phase status for release endpoint to start the release phase. At a minimum, you must provide `{"status": active}` in the request object to start a pipeline phase. If the phase requires approvals or guarded rollouts, provide the additional required information in the `audiences` list.


    ### Configuring release pipelines


    Use the related release pipelines API to view, create, update, and delete release pipelines, or to view the progress of all ongoing releases across all flags in a project for a given release pipeline.'
paths:
  /api/v2/flags/{projectKey}/{flagKey}/release:
    get:
      responses:
        '200':
          description: Release response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '404':
          description: Invalid resource identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorRep'
      tags:
      - Releases (beta)
      summary: Get release for flag
      description: Get currently active release for a flag
      parameters:
      - name: projectKey
        in: path
        description: The project key
        required: true
        schema:
          type: string
          format: string
          description: The project key
      - name: flagKey
        in: path
        description: The flag key
        required: true
        schema:
          type: string
          format: string
          description: The flag key
      operationId: getReleaseByFlagKey
    patch:
      responses:
        '200':
          description: Release response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestErrorRep'
        '401':
          description: Invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorRep'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorRep'
        '404':
          description: Invalid resource identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorRep'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorRep'
      tags:
      - Releases (beta)
      summary: Patch release for flag
      description: 'This endpoint is only available for releases that are part of a legacy release pipeline. Releases for new release pipelines should use the Update phase status for release endpoint.


        Update currently active release for a flag. Updating releases requires the JSON patch format. To learn more, read Updates.


        You can only use this endpoint to mark a release phase complete or incomplete. To indicate which phase to update, use the array index in the `path`. For example, to mark the first phase of a release as complete, use the following request body:


        ```

        [

        {

        "op": "replace",

        "path": "/phase/0/complete",

        "value": true

        }

        ]

        ```'
      parameters:
      - name: projectKey
        in: path
        description: The project key
        required: true
        schema:
          type: string
          format: string
          description: The project key
      - name: flagKey
        in: path
        description: The flag key
        required: true
        schema:
          type: string
          format: string
          description: The flag key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONPatch'
            example:
            - op: replace
              path: /phases/0/complete
              value: true
        required: true
      operationId: patchReleaseByFlagKey
    delete:
      responses:
        '204':
          description: Action succeeded
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorRep'
        '404':
          description: Invalid resource identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorRep'
      tags:
      - Releases (beta)
      summary: Delete a release for flag
      description: Deletes a release from a flag
      parameters:
      - name: projectKey
        in: path
        description: The project key
        required: true
        schema:
          type: string
          format: string
          description: The project key
      - name: flagKey
        in: path
        description: The flag key
        required: true
        schema:
          type: string
          format: string
          description: The flag key
      operationId: deleteReleaseByFlagKey
  /api/v2/projects/{projectKey}/flags/{flagKey}/release:
    put:
      responses:
        '200':
          description: Release response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestErrorRep'
        '401':
          description: Invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorRep'
        '404':
          description: Invalid resource identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorRep'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorRep'
      tags:
      - Releases (beta)
      summary: Create a new release for flag
      description: Creates a release by adding a flag to a release pipeline
      parameters:
      - name: projectKey
        in: path
        description: The project key
        required: true
        schema:
          type: string
          format: string
          description: The project key
      - name: flagKey
        in: path
        description: The flag key
        required: true
        schema:
          type: string
          format: string
          description: The flag key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReleaseInput'
        required: true
      operationId: createReleaseForFlag
  /api/v2/projects/{projectKey}/flags/{flagKey}/release/phases/{phaseId}:
    put:
      responses:
        '200':
          description: Action succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestErrorRep'
        '401':
          description: Invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorRep'
        '404':
          description: release or phase not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorRep'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorRep'
      tags:
      - Releases (beta)
      summary: Update phase status for release
      description: Updates the execution status of a phase of a release
      parameters:
      - name: projectKey
        in: path
        description: The project key
        required: true
        schema:
          type: string
          format: string
          description: The project key
      - name: flagKey
        in: path
        description: The flag key
        required: true
        schema:
          type: string
          format: string
          description: The flag key
      - name: phaseId
        in: path
        description: The phase ID
        required: true
        schema:
          type: string
          format: string
          description: The phase ID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhaseStatusInput'
        required: true
      operationId: updatePhaseStatus
components:
  schemas:
    JSONPatch:
      type: array
      items:
        $ref: '#/components/schemas/PatchOperation'
    PhaseConfiguration:
      type: object
      properties: {}
    PhaseStatus:
      type: string
    AudienceStatus:
      type: string
    InvalidRequestErrorRep:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Specific error code encountered
          example: invalid_request
        message:
          type: string
          description: Description of the error
          example: Invalid request body
    Release:
      type: object
      required:
      - name
      - releasePipelineKey
      - releasePipelineDescription
      - phases
      - _version
      properties:
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        name:
          type: string
          description: The release pipeline name
          example: Example release pipeline
        releasePipelineKey:
          type: string
          description: The release pipeline key
          example: example-release-pipeline
        releasePipelineDescription:
          type: string
          description: The release pipeline description
          example: Our release pipeline for typical testing and deployment
        phases:
          type: array
          description: An ordered list of the release pipeline phases
          items:
            $ref: '#/components/schemas/PipelineReleasePhase'
        _version:
          type: integer
          description: The release version
          example: 1
        _releaseVariationId:
          type: string
          description: The chosen release variation ID to use across all phases of a release
        _canceledAt:
          description: Timestamp of when the release was canceled
          example: '1684262711507'
          $ref: '#/components/schemas/UnixMillis'
    MemberSummary:
      type: object
      required:
      - _links
      - _id
      - role
      - email
      properties:
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
          example:
            self:
              href: /api/v2/members/569f183514f4432160000007
              type: application/json
        _id:
          type: string
          description: The member's ID
          example: 569f183514f4432160000007
        firstName:
          type: string
          description: The member's first name
          example: Ariel
        lastName:
          type: string
          description: The member's last name
          example: Flores
        role:
          type: string
          description: The member's base role. If the member has no additional roles, this role will be in effect.
          example: admin
        email:
          type: string
          description: The member's email address
          example: ariel@acme.com
    RateLimitedErrorRep:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Specific error code encountered
          example: rate_limited
        message:
          type: string
          description: Description of the error
          example: You've exceeded the API rate limit. Try again later.
    UnauthorizedErrorRep:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Specific error code encountered
          example: unauthorized
        message:
          type: string
          description: Description of the error
          example: Invalid access token
    ForbiddenErrorRep:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Specific error code encountered
          example: forbidden
        message:
          type: string
          description: Description of the error
          example: Forbidden. Access to the requested resource was denied.
    AudienceConfiguration:
      type: object
      required:
      - releaseStrategy
      - requireApproval
      properties:
        releaseStrategy:
          description: The release strategy
          example: monitoredRelease
          $ref: '#/components/schemas/ReleaseStrategy'
        requireApproval:
          type: boolean
          description: Whether or not the audience requires approval
          example: true
        notifyMemberIds:
          type: array
          description: An array of member IDs. These members are notified to review the approval request.
          items:
            type: string
          example:
          - 1234a56b7c89d012345e678f
        notifyTeamKeys:
          type: array
          description: An array of team keys. The members of these teams are notified to review the approval request.
          items:
            type: string
          example:
          - example-reviewer-team
        releaseGuardianConfiguration:
          description: The configuration for the release guardian.
          $ref: '#/components/schemas/ReleaseGuardianConfiguration'
    Link:
      type: object
      properties:
        href:
          type: string
        type:
          type: string
    ReleaseAudience:
      type: object
      required:
      - _id
      - name
      properties:
        _id:
          type: string
          description: The audience ID
          example: 1234a56b7c89d012345e678g
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        environment:
          description: Details about the environment. If the environment is deleted, this field will be omitted.
          $ref: '#/components/schemas/EnvironmentSummary'
        name:
          type: string
          description: The release phase name
          example: Phase 1 - Testing
        configuration:
          description: The audience configuration
          $ref: '#/components/schemas/AudienceConfiguration'
        segmentKeys:
          type: array
          description: A list of segment keys
          items:
            type: string
          example:
          - segment-key-123abc
        status:
          description: The audience status
          example: active
          $ref: '#/components/schemas/AudienceStatus'
        _ruleIds:
          type: array
          description: The rules IDs added or updated by this audience
          items:
            type: string
    UnixMillis:
      type: integer
      format: int64
    PatchOperation:
      type: object
      required:
      - op
      - path
      properties:
        op:
          type: string
          description: The type of operation to perform
          example: replace
        path:
          type: string
          description: A JSON Pointer string specifying the part of the document to operate on
          example: /exampleField
        value:
          description: A JSON value used in "add", "replace", and "test" operations
          example: new example value
    ReleaseStrategy:
      type: string
    ReleaseGuardianConfiguration:
      type: object
      required:
      - monitoringWindowMilliseconds
      - rolloutWeight
      - rollbackOnRegression
      properties:
        monitoringWindowMilliseconds:
          type: integer
          format: int64
          description: The monitoring window in milliseconds
          example: 60000
        rolloutWeight:
          type: integer
          description: The rollout weight percentage
          example: 50
        rollbackOnRegression:
          type: boolean
          description: Whether or not to roll back on regression
          example: true
        randomizationUnit:
          type: string
          description: The randomization unit for the measured rollout
          example: user
    NotFoundErrorRep:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Specific error code encountered
          example: not_found
        message:
          type: string
          description: Description of the error
          example: Invalid resource identifier
    ReleaserAudienceConfigInput:
      type: object
      properties:
        audienceId:
          type: string
          description: UUID of the audience.
        releaseGuardianConfiguration:
          description: Optional configuration details for the specified audience. Will default to the release pipeline's audience configuration if omitted.
          $ref: '#/components/schemas/ReleaseGuardianConfigurationInput'
        notifyMemberIds:
          type: array
          description: An array of member IDs. These members are notified to review the approval request.
          items:
            type: string
          example:
          - 1234a56b7c89d012345e678f
        notifyTeamKeys:
          type: array
          description: An array of team keys. The members of these teams are notified to review the approval request.
          items:
            type: string
          example:
          - example-reviewer-team
    TokenSummary:
      type: object
      properties:
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
        _id:
          type: string
        name:
          type: string
          description: The name of the token
          example: DevOps token
        ending:
          type: string
          description: The last few characters of the token
          example: '2345'
        serviceToken:
          type: boolean
          description: Whether this is a service token
          example: false
    PipelineReleasePhase:
      type: object
      required:
      - _id
      - _name
      - complete
      - _creationDate
      - _audiences
      properties:
        _id:
          type: string
          description: The phase ID
          example: 1234a56b7c89d012345e678f
        _name:
          type: string
          description: The release phase name
          example: Phase 1 - Testing
        complete:
          type: boolean
          description: Whether this phase is complete
          example: true
        _creationDate:
          description: Timestamp of when the release phase was created
          example: '1684262711507'
          $ref: '#/components/schemas/UnixMillis'
        _completionDate:
          description: Timestamp of when the release phase was completed
          example: '1684262711509'
          $ref: '#/components/schemas/UnixMillis'
        _completedBy:
          description: Details about how this phase was marked as complete
          $ref: '#/components/schemas/CompletedBy'
        _audiences:
          type: array
          description: A logical grouping of one or more environments that share attributes for rolling out changes
          items:
            $ref: '#/components/schemas/ReleaseAudience'
        status:
          description: Status of the phase
          example: Started
          enum:
          - NotStarted
          - ReadyToStart
          - Started
          - Paused
          - Complete
          $ref: '#/components/schemas/PhaseStatus'
        started:
          type: boolean
          description: Whether or not this phase has started
        _startedDate:
          description: Timestamp of when the release phase was started
          $ref: '#/components/schemas/UnixMillis'
        configuration:
          description: The phase configuration
          $ref: '#/components/schemas/PhaseConfiguration'
    UpdatePhaseStatusInput:
      type: object
      properties:
        status:
          description: Status of the phase
          example: Started
          enum:
          - NotStarted
          - ReadyToStart
          - Started
          - Paused
          - Complete
          $ref: '#/components/schemas/PhaseStatus'
        audiences:
          type: array
          description: Extra configuration for audiences required upon phase initialization.
          items:
            $ref: '#/components/schemas/ReleaserAudienceConfigInput'
    CreateReleaseInput:
      type: object
      required:
      - releasePipelineKey
      properties:
        releaseVariationId:
          type: string
          description: The variation id to release to across all phases
        releasePipelineKey:
          type: string
          description: The key of the release pipeline to attach the flag to
    ReleaseGuardianConfigurationInput:
      type: object
      properties:
        monitoringWindowMilliseconds:
          type: integer
          format: int64
          description: The monitoring window in milliseconds
          example: 60000
        rolloutWeight:
          type: integer
          description: The rollout weight
          example: 50
        rollbackOnRegression:
          type: boolean
          description: Whether or not to rollback on regression
          example: true
        randomizationUnit:
          type: string
          description: The randomization unit for the measured rollout
          example: user
    EnvironmentSummary:
      type: object
      required:
      - _links
      - key
      - name
      - color
      properties:
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
          example:
            self:
              href: /api/v2/projects/my-project/environments/my-environment
              type: application/json
        key:
          type: string
          description: A project-unique key for the environment
          example: environment-key-123abc
        name:
          type: string
          description: A human-friendly name for the environment
          example: My Environment
        color:
          type: string
          description: The color used to indicate this environment in the UI
          example: F5A623
    CompletedBy:
      type: object
      properties:
        member:
          description: The LaunchDarkly member who marked this phase as complete
          $ref: '#/components/schemas/MemberSummary'
        token:
          description: The service token used to mark this phase as complete
          $ref: '#/components/schemas/TokenSummary'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
x-provenance:
  method: harvested
  publisher: LaunchDarkly
  source: https://app.launchdarkly.com/api/v2/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)