openapi: 3.2.0
info:
  title: CloudBees Unify API (Current) Flags API
  version: 1.0.0
  description: API documentation for CloudBees Unify's current, stable endpoints.
servers:
- url: https://api.cloudbees.io
  description: CloudBees Unify Production API
security:
- BearerAuth: []
tags:
- name: Flags
  description: Control runtime feature visibility and behavior to enable gradual rollouts, A/B testing, progressive delivery, and safe deployments without redeployment.
paths:
  /v2/applications/{applicationId}/flags:
    get:
      tags:
      - Flags
      operationId: FlagApi_ListFlags
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application whose feature flags are to be listed.
        required: true
        schema:
          type: string
      - name: configStateEnvs
        in: query
        description: List of environment IDs for which to include the enabled/disabled state of each flag. When omitted, no configuration state is returned.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.ListFlagsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List feature flags
      description: Returns all feature flags for the specified application. Use the configStateEnvs query parameter to include the enabled/disabled state of each flag per environment.
    post:
      tags:
      - Flags
      operationId: FlagApi_AddFlag
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application in which to create the feature flag.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.flag.Flag'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.AddFlagResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Create a feature flag
      description: Creates a new feature flag within the specified application.
  /v2/applications/{applicationId}/flags/by-name/{name}:
    get:
      tags:
      - Flags
      operationId: FlagApi_GetFlagByName
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: name
        in: path
        description: Unique name of the feature flag to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.GetFlagResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get a feature flag by name
      description: Returns a single feature flag by its unique name within the specified application.
  /v2/applications/{applicationId}/flags/labels:
    get:
      tags:
      - Flags
      operationId: FlagApi_ListLabels
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application whose flag labels are to be listed.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.ListLabelsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List flag labels
      description: Returns all labels associated with feature flags in the specified application.
  /v2/applications/{applicationId}/flags/{id}:
    get:
      tags:
      - Flags
      operationId: FlagApi_GetFlag
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the feature flag to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.GetFlagResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get a feature flag
      description: Returns a single feature flag by its unique identifier within the specified application.
    put:
      tags:
      - Flags
      operationId: FlagApi_UpdateFlag
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the feature flag to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.flag.Flag'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.UpdateFlagResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Update a feature flag
      description: Replaces the configuration of an existing feature flag within the specified application. All fields in the request body replace the current values.
    delete:
      tags:
      - Flags
      operationId: FlagApi_DeleteFlag
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the feature flag to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Delete a feature flag
      description: Permanently deletes a feature flag and all its configurations from the specified application.
  /v2/applications/{applicationId}/flags/{id}/configuration-state:
    get:
      tags:
      - Flags
      description: Returns the enabled or disabled state of a feature flag for each environment in the application.
      operationId: FlagApi_GetFlagConfigurationState
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the feature flag whose configuration state is to be retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.GetFlagConfigurationStateResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag configuration state per environment
  /v2/applications/{applicationId}/flags/{id}/flag-usage-per-environment:
    get:
      tags:
      - Flags
      operationId: FlagApi_GetFlagFlagUsagePerEnvironment
      parameters:
      - name: applicationId
        in: path
        description: Unique identifier of the application that owns the feature flag.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Unique identifier of the feature flag to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.GetFlagFlagsUsagePerEnvironmentResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag target group usage per environment
      description: Returns the target groups referenced by a feature flag, grouped by environment.
components:
  schemas:
    api.flag.UpdateFlagResponse:
      type: object
      properties:
        flag:
          allOf:
          - $ref: '#/components/schemas/api.flag.Flag'
          description: The feature flag object reflecting its state after the update.
    api.flag.AddFlagResponse:
      type: object
      properties:
        flag:
          allOf:
          - $ref: '#/components/schemas/api.flag.Flag'
          description: The feature flag object as it was created, including its assigned identifier.
    api.flag.GetFlagConfigurationStateResponse:
      type: object
      properties:
        configurationStates:
          type: array
          items:
            $ref: '#/components/schemas/api.flag.FlagConfigurationState'
          description: The enabled/disabled state of the feature flag for each environment in the application.
    google.rpc.Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    api.TargetGroup.FlagUsageInEnvironment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the feature flag.
        name:
          type: string
          description: Display name of the feature flag.
        enabled:
          type: boolean
          description: Whether the feature flag is enabled in this environment.
        resourceId:
          type: string
          description: Unique identifier of the application that owns this feature flag.
    api.flag.ListFlagsResponse:
      type: object
      properties:
        flags:
          type: array
          items:
            $ref: '#/components/schemas/api.flag.Flag'
          description: The list of feature flags belonging to the specified application.
    api.flag.GetFlagFlagsUsagePerEnvironmentResponse:
      type: object
      properties:
        environments:
          type: array
          items:
            $ref: '#/components/schemas/api.TargetGroup.EnvironmentUsage'
          description: The list of environments and the target groups that this feature flag references in each.
    api.TargetGroup.EnvironmentUsage:
      type: object
      properties:
        environmentId:
          type: string
          description: Unique identifier of the environment.
        flagUsage:
          type: array
          items:
            $ref: '#/components/schemas/api.TargetGroup.FlagUsageInEnvironment'
          description: Feature flags that reference the target group in this environment.
    api.flag.GetFlagResponse:
      type: object
      properties:
        flag:
          allOf:
          - $ref: '#/components/schemas/api.flag.Flag'
          description: The feature flag object containing its current configuration and metadata.
    api.flag.FlagConfigurationState:
      type: object
      properties:
        environmentId:
          type: string
          description: The unique identifier of the environment this state applies to.
        enabled:
          type: boolean
          description: Whether the feature flag is enabled in this environment.
        updated:
          type: string
          description: The date and time at which this configuration state was last updated.
          format: date-time
    google.protobuf.Any:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    api.flag.Flag:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the feature flag.
        name:
          type: string
          description: The unique name of the feature flag within the application.
        description:
          type: string
          description: A human-readable description of the feature flag's purpose.
        flagType:
          enum:
          - Boolean
          - String
          - Number
          type: string
          description: The value type of the flag. One of Boolean, String, or Number.
        variants:
          type: array
          items:
            type: string
          description: The valid variant values for String or Number flags. Empty for Boolean flags.
        resourceId:
          type: string
          description: The unique identifier of the application that owns this feature flag.
        labels:
          type: array
          items:
            type: string
          description: Labels attached to this feature flag for organizational or filtering purposes.
        isPermanent:
          type: boolean
          description: When true, the flag is marked permanent and excluded from stale flag cleanup.
        cascUrl:
          type: string
          description: The CasC (Configuration as Code) URL for this feature flag.
        created:
          type: string
          description: The date and time at which the feature flag was created.
          format: date-time
        configStates:
          type: array
          items:
            $ref: '#/components/schemas/api.flag.FlagConfigurationState'
          description: The enabled or disabled state of this flag per environment. Populated only when environment IDs are requested.
        updated:
          type: string
          description: The date and time at which the feature flag was last updated.
          format: date-time
    api.flag.ListLabelsResponse:
      type: object
      properties:
        labels:
          type: array
          items:
            type: string
          description: The list of label strings associated with feature flags in the application.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: CloudBees Unify API access token or personal access token
x-tagGroups:
- name: Unify core
  tags:
  - Components
  - Environments
  - Organizations
  - Teams
  - Users
- name: Feature management
  tags:
  - Flags
  - Flag configurations
  - Flag custom properties
  - Target groups
  - Flag lifecycle