CloudBees Unify Platform API

openapi: 3.0.3
info:
  title: CloudBees Unify API (Current)
  version: 1.0.0
  description: |-
    API documentation for CloudBees Unify's current, stable endpoints. This specification covers the endpoints customers rely on today while next-generation v4 equivalents are in development. These endpoints are stable and supported, but no longer receive new features.

    ### Unify core

    #### Components
    List components within an organization, and optionally filter by component type, such as applications or services with an associated repository.

    #### Environments
    Discover and manage environments within your organization. Use environments to maintain an up-to-date inventory for feature flag targeting, deployment scripts, and monitoring workflows.

    #### Organizations
    Define the structural and governance boundaries within a CloudBees Unify tenant. Organizations model business units or departments, support parent-child hierarchies, and inherit configuration—properties, integrations, and environments—from parent organizations. Every tenant has one root organization; all others exist beneath it.

    #### Teams
    List teams within an organization. Teams group users to manage access and permissions across resources in CloudBees Unify.

    #### Users
    Invite or remove users, and define custom attributes for feature flag targeting based on application-specific criteria such as account tier, region, or subscription status.

    ### Feature management

    #### Flags
    Control runtime feature visibility and behavior to enable gradual rollouts, A/B testing, progressive delivery, and safe deployments without redeployment.

    #### Flag configurations
    Set flag state (enabled or disabled) and targeting rules for a specific environment to determine which users or segments receive each variation.

    #### Flag custom properties
    Create, read, update, and delete custom properties used in targeting conditions and target groups.

    #### Target groups
    Define reusable sets of targeting conditions for feature flags. Specify rules once (such as matching users by role, region, or custom property) and apply them across multiple flags. Changes to a target group propagate automatically to every flag that references it.

    #### Flag lifecycle
    Track how often each flag variation is served in an environment. Use impression data to monitor adoption, validate rollouts, and see which variations your application evaluates.

    For new integrations, prefer the [CloudBees Unify API (Beta)](https://calculi-corp.github.io/api/#v4-public) where available.
paths:
  /v1/applications/{organizationId}/environments/{environmentId}/flags-status:
    get:
      tags:
        - Flag lifecycle
      operationId: FmImpressionsApi_GetFlagsStatus2
      parameters:
        - name: organizationId
          in: path
          description: Unique identifier of the application that contains the environment.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment whose flag statuses are to be returned.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.fmimpressions.GetFlagsStatusResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag statuses
      description: Returns the current status of all feature flags within the specified environment.
  /v1/applications/{organizationId}/environments/{environmentId}/impressions:
    post:
      tags:
        - Flag lifecycle
      operationId: FmImpressionsApi_GetImpressions2
      parameters:
        - name: organizationId
          in: path
          description: Unique identifier of the application that contains the environment.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment whose flag impressions are to be returned.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.fmimpressions.ImpressionParams'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.fmimpressions.GetImpressionsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag impressions
      description: Returns aggregated impression data for one or more feature flags within the specified environment. Use the mode and time range parameters to control the aggregation granularity and the time window of results.
  /v1/organizations:
    get:
      tags:
        - Organizations
      operationId: listOrganizations
      parameters:
        - name: userId
          in: query
          description: When provided, returns only organizations that the specified user is a member of.
          schema:
            type: string
        - name: nested
          in: query
          description: When true, returns sub-organizations nested under their parent organizations. Defaults to false.
          schema:
            type: boolean
        - name: tenant
          in: query
          description: When true, returns only top-level tenant organizations. Defaults to false.
          schema:
            type: boolean
        - name: domainName
          in: query
          description: When provided, returns only organizations whose domain name exactly matches this value.
          schema:
            type: string
        - name: includeDeleted
          in: query
          description: When true, includes deleted organizations in the results. Defaults to false.
          schema:
            type: boolean
        - name: pagination.page
          in: query
          description: page (optional) indicates which page is being requested or returned (0 or 1) returns the 1st page of results
          schema:
            type: integer
            format: int32
        - name: pagination.pageLength
          in: query
          description: |-
            page_length (optional) specifies the number of items per page being requested.  If the request is asking for more than an api limit
             allows, the response will indicate the new page_length that should be used for future calls.
          schema:
            type: integer
            format: int32
        - name: pagination.sort.fieldName
          in: query
          description: |-
            field_name specifies the field to use for sorting a list of results.  See documentation for
             specific API endpoints to determine appropriate field names.
          schema:
            type: string
        - name: pagination.sort.order
          in: query
          description: order specifies how to sort the results
          schema:
            enum:
              - ASCENDING
              - DESCENDING
            type: string
        - name: pagination.lastPage
          in: query
          description: 'RESPONSE ONLY: last_page is true {response} if there are no more results to be returned'
          schema:
            type: boolean
        - name: include
          in: query
          description: Comma-separated list of related resources to include in the response, for example `teams` or `roles`.
          schema:
            type: string
        - name: name
          in: query
          description: Partial name to filter results. Returns organizations whose domain name or display name contains this value.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.auth.GetOrganizationsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List organizations
      description: Returns a list of organizations accessible to the authenticated user.
  /v1/organizations/name:
    get:
      tags:
        - Organizations
      operationId: getOrganizationByName
      parameters:
        - name: name
          in: query
          description: Domain name of the organization to look up. Must be an exact match. Required.
          schema:
            type: string
        - name: nested
          in: query
          description: When true, includes and nests all child organizations under the returned organization. Defaults to false.
          schema:
            type: boolean
        - name: userId
          in: query
          description: When provided, returns the organization only if the specified user has permission to access it.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.auth.GetOrganizationByNameResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get organization by name
      description: Returns the top-level organization whose name exactly matches the provided value.
  /v1/organizations/{orgId}/services:
    get:
      tags:
        - Components
      description: Returns a list of applications and components within the specified organization.
      operationId: ServiceEndpoint_ListServices2
      parameters:
        - name: orgId
          in: path
          description: Unique identifier of the organization whose applications and components are to be listed.
          required: true
          schema:
            type: string
        - name: typeFilter
          in: query
          description: Filters the results by type. Defaults to SERVICE_WITH_REPO_FILTER when omitted, which returns only components with an associated repository.
          schema:
            enum:
              - SERVICE_WITH_REPO_FILTER
              - APPLICATION_FILTER
              - COMPONENT_FILTER
              - NO_FILTER
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.service.ListServicesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List applications and components
  /v1/organizations/{organizationId}/teams:
    get:
      tags:
        - Teams
      operationId: TeamsService_GetTeams
      parameters:
        - name: organizationId
          in: path
          description: Unique identifier of the organization whose teams are to be listed. Required.
          required: true
          schema:
            type: string
        - name: userId
          in: query
          description: Filters results to teams that include the specified user as a member. Omit to return all teams in the organization.
          schema:
            type: string
        - name: pagination.page
          in: query
          description: page (optional) indicates which page is being requested or returned (0 or 1) returns the 1st page of results
          schema:
            type: integer
            format: int32
        - name: pagination.pageLength
          in: query
          description: |-
            page_length (optional) specifies the number of items per page being requested.  If the request is asking for more than an api limit
             allows, the response will indicate the new page_length that should be used for future calls.
          schema:
            type: integer
            format: int32
        - name: pagination.sort.fieldName
          in: query
          description: |-
            field_name specifies the field to use for sorting a list of results.  See documentation for
             specific API endpoints to determine appropriate field names.
          schema:
            type: string
        - name: pagination.sort.order
          in: query
          description: order specifies how to sort the results
          schema:
            enum:
              - ASCENDING
              - DESCENDING
            type: string
        - name: pagination.lastPage
          in: query
          description: 'RESPONSE ONLY: last_page is true {response} if there are no more results to be returned'
          schema:
            type: boolean
        - name: include
          in: query
          description: Optional comma-separated list of related resources to include in each team response, for example `users` or `roles`.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.auth.GetTeamsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List teams in an organization
      description: Returns a list of teams within the specified organization. Use the `userId` query parameter to filter results to teams that include a specific user as a member.
  /v2/applications/{applicationId}/custom-properties:
    get:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_ListCustomProperties
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application whose custom properties are to be listed.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.ListCustomPropertiesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List custom properties
      description: Returns all custom properties defined within the specified application.
    post:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_AddCustomProperty
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application in which to create the custom property.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.CustomProperty.CustomProperty'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.AddCustomPropertyResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Create a custom property
      description: Creates a new custom property within the specified application. Custom properties define additional attributes that can be used in feature flag targeting rules.
  /v2/applications/{applicationId}/custom-properties/by-name/{name}:
    get:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_GetCustomPropertyByName
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: Name of the custom property to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.GetCustomPropertyResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get a custom property by name
      description: Returns a single custom property matching the specified name within the application. Use this endpoint when you have the property name but not its ID.
  /v2/applications/{applicationId}/custom-properties/{id}:
    get:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_GetCustomProperty
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Unique identifier of the custom property to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.GetCustomPropertyResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get a custom property
      description: Returns a single custom property by its unique identifier within the specified application.
    put:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_UpdateCustomProperty
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Unique identifier of the custom property to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.CustomProperty.CustomProperty'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.UpdateCustomPropertyResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Update a custom property
      description: Replaces all fields of the specified custom property with the provided values. All fields in the request body are required; omitted fields are set to their default values.
    delete:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_DeleteCustomProperty
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Unique identifier of the custom property 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 custom property
      description: Permanently deletes the specified custom property. This action cannot be undone. Ensure the property is not referenced by any feature flag targeting rules before deleting.
  /v2/applications/{applicationId}/custom-properties/{id}/flag-usage-per-environment:
    get:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_GetCustomPropertyFlagUsagePerEnvironment
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Unique identifier of the custom property to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.GetCustomPropertyFlagsUsagePerEnvironmentResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag usage per environment
      description: Returns a list of environments and the feature flags that reference this custom property in each environment. Use this to understand where a custom property is actively used before modifying or deleting it.
  /v2/applications/{applicationId}/custom-properties/{id}/target-group-usage:
    get:
      tags:
        - Flag custom properties
      operationId: CustomPropertyApi_GetCustomPropertyTargetGroupUsage
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the custom property.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: Unique identifier of the custom property to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.CustomProperty.GetCustomPropertyTargetGroupUsageResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get target group usage
      description: Returns the target groups that reference this custom property in their targeting rules. Use this to understand the impact of changes to a custom property before modifying or deleting it.
  /v2/applications/{applicationId}/environments/{environmentId}/configuration:
    get:
      tags:
        - Flag configurations
      operationId: FlagConfigurationApi_ListFlagConfigurations
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application whose flag configurations are to be listed.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment for which to list flag configurations.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.ListFlagConfigurationsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: List flag configurations for an environment
      description: Returns the configurations of all feature flags within the specified environment of an application.
  /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/{flagId}/configuration/environments/{environmentId}:
    get:
      tags:
        - Flag configurations
      operationId: FlagConfigurationApi_GetFlagConfiguration
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the feature flag.
          required: true
          schema:
            type: string
        - name: flagId
          in: path
          description: Unique identifier of the feature flag whose configuration is to be retrieved.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment for which to retrieve the flag configuration.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.flag.GetFlagConfigurationResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Get flag configuration for an environment
      description: Returns the configuration of a feature flag for the specified environment within an application.
    put:
      tags:
        - Flag configurations
      operationId: FlagConfigurationApi_UpdateFlagConfiguration
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the feature flag.
          required: true
          schema:
            type: string
        - name: flagId
          in: path
          description: Unique identifier of the feature flag to update.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment for which to update the flag configuration.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.flag.FlagConfiguration'
        required: true
      responses:
        '200':
          description: OK
          content: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google.rpc.Status'
      summary: Update flag configuration for an environment
      description: Replaces the full configuration of a feature flag for the specified environment within an application.
    patch:
      tags:
        - Flag configurations
      operationId: FlagConfigurationApi_PatchFlagConfiguration
      parameters:
        - name: applicationId
          in: path
          description: Unique identifier of the application that owns the feature flag.
          required: true
          schema:
            type: string
        - name: flagId
          in: path
          description: Unique identifier of the feature flag to update.
          required: true
          schema:
            type: string
        - name: environmentId
          in: path
          description: Unique identifier of the environment for which to update the flag configuration.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
          

# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cloudbees/refs/heads/main/openapi/cloudbees-unify-openapi.yml