openapi: 3.1.0
info:
  title: DevCycle Bucketing Audiences Bucketing API 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: Bucketing API
paths:
  /v1/variables/{key}:
    post:
      summary: Get variable by key for user data
      tags:
      - Bucketing API
      operationId: getVariableByKey
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        description: Variable key
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9-_.]+$
          example: my-variable-key
      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'
      responses:
        200:
          description: Variable response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variable'
              example:
                _id: 614ef6ea475129459160721a
                _feature: 614ef6aa473928459060721a
                key: my-variable-key
                type: String
                value: feature-enabled
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
  /v1/variables:
    post:
      summary: Get all variables by key for user data
      tags:
      - Bucketing API
      security:
      - bearerAuth: []
      operationId: getVariables
      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'
      responses:
        200:
          description: Variables response (map of variable keys to Variable objects)
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Variable'
              example:
                my-string-var:
                  _id: 614ef6ea475129459160721a
                  _feature: 614ef6aa473928459060721a
                  key: my-string-var
                  type: String
                  value: enabled
                my-boolean-var:
                  _id: 614ef6ea475139459160721b
                  _feature: 614ef6aa473928459060721b
                  key: my-boolean-var
                  type: Boolean
                  value: true
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
  /v1/features:
    post:
      summary: Get all features by key for user data
      tags:
      - Bucketing API
      operationId: getFeatures
      security:
      - bearerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'
      responses:
        200:
          description: Features response (map of Feature keys to Feature objects)
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Feature'
              example:
                new-dashboard:
                  _id: 614ef6aa473928459060721a
                  key: new-dashboard
                  type: release
                  _variation: 614ef6ea4753284590607216
                  variationName: Variation On
                  variationKey: variation-on
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
  /v1/track:
    post:
      summary: Post events to DevCycle for user
      tags:
      - Bucketing API
      security:
      - bearerAuth: []
      operationId: postEvents
      requestBody:
        $ref: '#/components/requestBodies/TrackRequestBody'
      responses:
        201:
          description: Events received successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully received 2 events.
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Error response status code
        message:
          type: string
          description: Error message
        data:
          type: object
          description: Additional error information detailing the error reasoning
      required:
      - message
    Feature:
      type: object
      properties:
        _id:
          type: string
          description: unique database id
        key:
          type: string
          pattern: ^[a-z0-9-_.]+$
          description: Unique key by Project, can be used in the SDK / API to reference by 'key' rather than _id.
        type:
          type: string
          description: Feature type
          enum:
          - release
          - experiment
          - permission
          - ops
        _variation:
          type: string
          description: Bucketed feature variation ID
        variationName:
          type: string
          description: Bucketed feature variation Name
        variationKey:
          type: string
          description: Bucketed feature variation Key
        eval:
          $ref: '#/components/schemas/EvalReason'
      required:
      - _id
      - key
      - type
      - _variation
    UserDataAndEventsBody:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        user:
          $ref: '#/components/schemas/UserData'
    EvalReason:
      type: object
      description: The reason the User was Served this particular value
      properties:
        reason:
          type: string
          description: Evaluation reason
          enum:
          - TARGETING_MATCH
          - DEFAULT
          - STATIC
        details:
          type: string
          description: Detailed description of evaluation
        target_id:
          type: string
          description: ID of the targeting rule that matched
      required:
      - reason
    Variable:
      type: object
      properties:
        _id:
          type: string
          description: unique database id
        _feature:
          type: string
          description: Feature ID that this variable belongs to
        key:
          type: string
          pattern: ^[a-z0-9-_.]+$
          description: Unique key by Project, can be used in the SDK / API to reference by 'key' rather than _id.
        type:
          type: string
          description: Variable type
          enum:
          - String
          - Boolean
          - Number
          - JSON
        value:
          description: Variable value can be a string, number, boolean, or JSON
          oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: object
        eval:
          $ref: '#/components/schemas/EvalReason'
      required:
      - _id
      - key
      - type
      - value
    UserData:
      type: object
      properties:
        user_id:
          type: string
          description: Unique id to identify the user
        email:
          type: string
          description: User's email used to identify the user on the dashboard / target audiences
        name:
          type: string
          description: User's name used to identify the user on the dashboard / target audiences
        language:
          type: string
          description: User's language in ISO 639-1 format
          maxLength: 2
        country:
          type: string
          description: User's country in ISO 3166 alpha-2 format
          maxLength: 2
        appVersion:
          type: string
          description: App Version of the running application
        appBuild:
          type: string
          description: App Build number of the running application
        customData:
          type: object
          description: User's custom data to target the user with, data will be logged to DevCycle for use in dashboard.
        privateCustomData:
          type: object
          description: User's custom data to target the user with, data will not be logged to DevCycle only used for feature bucketing.
        createdDate:
          type: number
          description: Date the user was created, Unix epoch timestamp format
        lastSeenDate:
          type: number
          description: Date the user was created, Unix epoch timestamp format
        platform:
          type: string
          description: Platform the Client SDK is running on
        platformVersion:
          type: string
          description: Version of the platform the Client SDK is running on
        deviceModel:
          type: string
          description: User's device model
        sdkType:
          type: string
          description: DevCycle SDK type
          enum:
          - api
          - server
          - client
          - mobile
        sdkVersion:
          type: string
          description: DevCycle SDK Version
      required:
      - user_id
    Event:
      type: object
      properties:
        type:
          type: string
          description: Custom event type
        target:
          type: string
          description: Custom event target / subject of event. Contextual to event type
        date:
          type: number
          description: Unix epoch time the event occurred according to client
        value:
          type: number
          description: Value for numerical events. Contextual to event type
        metaData:
          type: object
          description: Extra JSON metadata for event. Contextual to event type
      required:
      - type
  responses:
    UnauthorizedError:
      description: Missing 'sdkKey' query parameter or 'Authorization' header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  requestBodies:
    UserRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserData'
          example:
            user_id: user_123456
            email: user@example.com
            name: John Doe
            country: US
            customData:
              plan: premium
              signupDate: '2024-01-01'
    TrackRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserDataAndEventsBody'
          example:
            user:
              user_id: user_123456
              email: user@example.com
              customData:
                plan: premium
            events:
            - type: purchase
              value: 99.99
              metaData:
                item: subscription
                currency: USD
            - type: feature_click
              target: new-dashboard-button
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Enter your DevCycle SDK token