openapi: 3.1.0
info:
  title: DevCycle Bucketing Audiences Environments API
  description: Documents the DevCycle Bucketing API which provides an API interface to User Bucketing and for Server SDKs configured to use Cloud Bucketing.
  version: 1.3.0
servers:
- url: https://bucketing-api.devcycle.com/
tags:
- name: Environments
paths:
  /v1/projects/{project}/environments:
    post:
      operationId: EnvironmentsController_create
      summary: Create Environment
      description: 'Create a new environment for a project. The environment key must be unique within the project. Multiple environments can share a type.

        Creating an environment will auto-generate a set of SDK Keys for the various types of SDKs.

        When permissions are enabled for the organization, the token must have Publisher permissions for the environment to be created.'
      tags:
      - Environments
      parameters:
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: ''
        '404':
          description: ''
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
    get:
      operationId: EnvironmentsController_findAll
      summary: List Environments
      description: List all environments for a project. If a token does not have permission to view protected environments the environments will be filtered to only show non-protected environments SDK Keys for security.
      tags:
      - Environments
      parameters:
      - name: page
        required: false
        in: query
        schema:
          minimum: 1
          default: 1
          type: number
      - name: perPage
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 1000
          default: 100
          type: number
      - name: sortBy
        required: false
        in: query
        schema:
          default: createdAt
          enum:
          - createdAt
          - updatedAt
          - name
          - key
          - propertyKey
          type: string
      - name: sortOrder
        required: false
        in: query
        schema:
          default: desc
          enum:
          - asc
          - desc
          type: string
      - name: search
        required: false
        in: query
        schema:
          minLength: 3
          type: string
      - name: createdBy
        required: false
        in: query
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Environment'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: ''
        '403':
          description: ''
        '404':
          description: ''
  /v1/projects/{project}/environments/{key}:
    get:
      operationId: EnvironmentsController_findOne
      summary: Get an Environment
      description: Returns the environment; if the token does not have permission to view protected environments, the environment will be filtered to only show non-protected SDK Keys for security.
      tags:
      - Environments
      parameters:
      - name: key
        required: true
        in: path
        description: A Environment key or ID
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '401':
          description: ''
        '403':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
    patch:
      operationId: EnvironmentsController_update
      summary: Update an Environment
      description: Update an environment by ID or key. The environment key (if edited) must be unique within the project. If permissions are enabled, changing a protected environment type requires Publisher permissions
      tags:
      - Environments
      parameters:
      - name: key
        required: true
        in: path
        description: A Environment key or ID
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEnvironmentDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: ''
        '404':
          description: Environment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '409':
          description: Environment key already exists, cannot rename an environment to an existing one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
    delete:
      operationId: EnvironmentsController_remove
      summary: Delete an Environment
      description: Delete an Environment by ID or key
      tags:
      - Environments
      parameters:
      - name: key
        required: true
        in: path
        description: A Environment key or ID
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      responses:
        '200':
          description: ''
        '401':
          description: ''
        '403':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '405':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CannotDeleteLastItemErrorResponse'
  /v1/projects/{project}/environments/{environment}/sdk-keys:
    post:
      operationId: SdkKeysController_generate
      summary: Generate SDK Keys
      description: 'Generate new SDK keys for an environment, for any or all of the SDK types. This is the expected and recommended way to rotate SDK keys. Adding a new SDK key will not invalidate existing SDK keys.

        Generating new keys is restricted for protected environments to those with Publisher permissions'
      tags:
      - Environments
      parameters:
      - name: environment
        required: true
        in: path
        description: An Environment key or ID
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSdkTokensDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: ''
        '403':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
  /v1/projects/{project}/environments/{environment}/sdk-keys/{key}:
    delete:
      operationId: SdkKeysController_invalidate
      summary: Invalidate an SDK key
      description: This will invalidate all configs associated with a given key. This is an instantaneous change and all SDKs using this key will stop working immediately. This is the expected and recommended way to rotate SDK keys.
      tags:
      - Environments
      parameters:
      - name: key
        required: true
        in: path
        description: An SDK key
        schema:
          type: string
      - name: environment
        required: true
        in: path
        description: An Environment key or ID
        schema:
          type: string
      - name: project
        required: true
        in: path
        description: A Project key or ID
        schema:
          type: string
      responses:
        '200':
          description: ''
        '401':
          description: ''
        '403':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '405':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CannotDeleteLastItemErrorResponse'
components:
  schemas:
    CannotDeleteLastItemErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Response status code
          example: 405
        message:
          type: object
          description: Error details
          example: Cannot DELETE last item
        error:
          type: string
          description: Error type
          example: Method Not Allowed
      required:
      - statusCode
      - message
      - error
    GenerateSdkTokensDto:
      type: object
      properties:
        client:
          type: boolean
        server:
          type: boolean
        mobile:
          type: boolean
    Environment:
      type: object
      properties:
        name:
          type: string
          description: A unique display name
          example: Staging Upcoming
          maxLength: 100
          minLength: 1
        key:
          type: string
          description: 'Unique Environment identifier, can be used in the SDK / API to reference by key rather than ID.

            Must only contain lower-case characters and `_`, `-` or `.`.'
          example: staging-upcoming
          minLength: 1
          maxLength: 100
          pattern: ^[a-z0-9-_.]+$
        description:
          type: string
          description: Environment description.
          example: Pre-production changes
          maxLength: 1000
        color:
          type: string
          description: 'Environment display color, used to highlight different environments on the dashboard.

            Must use Hex color code.'
          example: '#4073FF'
          maxLength: 9
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
        _id:
          type: string
          description: A unique Environment ID
          example: 61450f3daec96f5cf4a49946
        _project:
          type: string
          description: The Project owning the Environment
        type:
          description: The environment type
          example: staging
          enum:
          - development
          - staging
          - production
          - disaster_recovery
          type: string
        _createdBy:
          type: string
          description: ID of the User who created the Environment.
        createdAt:
          format: date-time
          type: string
          description: The date the Environment was created
        updatedAt:
          format: date-time
          type: string
          description: The date the Environment was last updated
        sdkKeys:
          description: 'SDK Keys for mobile SDKs / client SDKs / server SDKs.

            Multiple keys can be created to allow for key rotation.'
          allOf:
          - $ref: '#/components/schemas/SDKKeys'
        settings:
          description: Environment based settings
          allOf:
          - $ref: '#/components/schemas/EnvironmentSettings'
        readonly:
          type: boolean
          description: Controls whether the environment is editable for a given user
      required:
      - name
      - key
      - _id
      - _project
      - type
      - _createdBy
      - createdAt
      - updatedAt
      - readonly
    APIKey:
      type: object
      properties: {}
    EnvironmentSettings:
      type: object
      properties:
        appIconURI:
          type: string
          description: A unique App Icon URI for a given environment
          maxLength: 2048
    SDKKeys:
      type: object
      properties:
        mobile:
          type: array
          items:
            $ref: '#/components/schemas/APIKey'
        client:
          type: array
          items:
            $ref: '#/components/schemas/APIKey'
        server:
          type: array
          items:
            $ref: '#/components/schemas/APIKey'
      required:
      - mobile
      - client
      - server
    BadRequestErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Response status code
          example: 400
        message:
          type: object
          description: Error details
          example:
          - key should not be empty
        error:
          type: string
          description: Error type
          example: Bad Request
      required:
      - statusCode
      - message
      - error
    ConflictErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Response status code
          example: 409
        message:
          type: object
          description: Error details
          example: Duplicate key 'key-123'
        error:
          type: string
          description: Error type
          example: Conflict
        errorType:
          type: string
          example: ERR_DUPE_FEATURE_KEY
      required:
      - statusCode
      - message
      - error
      - errorType
    NotFoundErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Response status code
          example: 404
        message:
          type: object
          description: Error details
          example: Item with key 'key-123' not found
        error:
          type: string
          description: Error type
          example: Not Found
      required:
      - statusCode
      - message
      - error
    CreateEnvironmentDto:
      type: object
      properties:
        name:
          type: string
          description: A unique display name
          example: Staging Upcoming
          maxLength: 100
          minLength: 1
        key:
          type: string
          description: 'Unique Environment identifier, can be used in the SDK / API to reference by key rather than ID.

            Must only contain lower-case characters and `_`, `-` or `.`.'
          example: staging-upcoming
          minLength: 1
          maxLength: 100
          pattern: ^[a-z0-9-_.]+$
        description:
          type: string
          description: Environment description.
          example: Pre-production changes
          maxLength: 1000
        color:
          type: string
          description: 'Environment display color, used to highlight different environments on the dashboard.

            Must use Hex color code.'
          example: '#4073FF'
          maxLength: 9
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
        type:
          type: string
          description: The environment type
          example: staging
          enum:
          - development
          - staging
          - production
          - disaster_recovery
        settings:
          description: Environment based settings
          allOf:
          - $ref: '#/components/schemas/EnvironmentSettings'
      required:
      - name
      - key
      - type
    UpdateEnvironmentDto:
      type: object
      properties:
        name:
          type: string
          description: A unique display name
          example: Staging Upcoming
          maxLength: 100
          minLength: 1
        key:
          type: string
          description: 'Unique Environment identifier, can be used in the SDK / API to reference by key rather than ID.

            Must only contain lower-case characters and `_`, `-` or `.`.'
          example: staging-upcoming
          minLength: 1
          maxLength: 100
          pattern: ^[a-z0-9-_.]+$
        description:
          type: string
          description: Environment description.
          example: Pre-production changes
          maxLength: 1000
        color:
          type: string
          description: 'Environment display color, used to highlight different environments on the dashboard.

            Must use Hex color code.'
          example: '#4073FF'
          maxLength: 9
          pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$
        type:
          description: The environment type
          example: staging
          enum:
          - development
          - staging
          - production
          - disaster_recovery
          type: string
        settings:
          description: Environment based settings
          allOf:
          - $ref: '#/components/schemas/EnvironmentSettings'
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Enter your DevCycle SDK token