Bluejay Customer Traits API

openapi: 3.1.0
info:
  title: Bluejay Agents Customer Traits API
  description: Bluejay API
  version: 0.1.0
servers:
- url: https://api.getbluejay.ai
  description: Production server
security:
- apiKeyAuth: []
tags:
- name: Customer Traits
paths:
  /v1/create-customer-trait:
    post:
      tags:
      - Customer Traits
      summary: Create Customer Trait
      description: "Create a new customer trait definition for an agent.\n\nArgs:\n    trait_request: The trait creation request data\n    request: FastAPI request object\n    auth: Authentication credentials\n\nReturns:\n    CustomerTraitResponse with the created trait details"
      operationId: create_customer_trait_v1_create_customer_trait_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerTraitRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTraitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/customer-trait/{trait_id}:
    get:
      tags:
      - Customer Traits
      summary: Get Customer Trait
      description: "Get a specific customer trait by ID.\n\nArgs:\n    trait_id: UUID of the customer trait\n    request: FastAPI request object\n    auth: Authentication credentials\n\nReturns:\n    CustomerTraitResponse with the trait details"
      operationId: get_customer_trait_v1_customer_trait__trait_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: trait_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Trait Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTraitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Customer Traits
      summary: Delete Customer Trait
      description: "Delete a customer trait definition.\n\nArgs:\n    trait_id: UUID of the customer trait to delete\n    request: FastAPI request object\n    auth: Authentication credentials\n\nReturns:\n    DeleteCustomerTraitResponse confirming the deletion"
      operationId: delete_customer_trait_v1_customer_trait__trait_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: trait_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Trait Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomerTraitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/customer-traits:
    get:
      tags:
      - Customer Traits
      summary: Get Customer Traits
      description: "Get all customer traits, optionally filtered by agent_id.\n\nArgs:\n    request: FastAPI request object\n    agent_id: Optional agent ID to filter traits by\n    auth: Authentication credentials\n\nReturns:\n    CustomerTraitsListResponse with list of traits and total count"
      operationId: get_customer_traits_v1_customer_traits_get
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Agent Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTraitsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/update-customer-trait/{trait_id}:
    put:
      tags:
      - Customer Traits
      summary: Update Customer Trait
      description: "Update a customer trait definition.\n\nArgs:\n    trait_id: UUID of the customer trait to update\n    trait_request: The trait update request data\n    request: FastAPI request object\n    auth: Authentication credentials\n\nReturns:\n    CustomerTraitResponse with the updated trait details"
      operationId: update_customer_trait_v1_update_customer_trait__trait_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: trait_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Trait Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerTraitRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerTraitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate-trait-values:
    post:
      tags:
      - Customer Traits
      summary: Generate Trait Values Endpoint
      description: "Generate trait values for each scenario for a single trait.\n\nRequest:\n    - scenarios: list of scenario descriptions (intents), one per scenario\n    - traits: exactly one trait (name + data_type)\n\nResponse:\n    - dict mapping scenario index -> list of trait dicts\n    - each trait dict has:\n        {\n            \"name\": <trait_name>,       # same as the input trait name\n            \"data_type\": <data_type>,   # normalized data type string\n            \"value\": <generated_value>, # value for that scenario + trait\n        }\n\nFrontend mapping:\n    - for scenario index i:\n        const traitsForScenario = res[i]; // array of trait dicts\n        const value = traitsForScenario.find(t => t.name === traitName)?.value;"
      operationId: generate_trait_values_endpoint_v1_generate_trait_values_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateTraitValuesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                title: Response Generate Trait Values Endpoint V1 Generate Trait Values Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DeleteCustomerTraitResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        deleted_trait_id:
          type: string
          title: Deleted Trait Id
          description: ID of the deleted trait
      type: object
      required:
      - message
      - deleted_trait_id
      title: DeleteCustomerTraitResponse
      description: Response model for deleting a customer trait.
    CustomerTraitResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the customer trait
        agent_id:
          type: integer
          title: Agent Id
          description: ID of the agent this trait belongs to
        name:
          type: string
          title: Name
          description: Name of the trait
        data_type:
          $ref: '#/components/schemas/TraitDataType'
          description: Data type of the trait
        default_value:
          anyOf:
          - {}
          - type: 'null'
          title: Default Value
          description: Default value for this trait (stored as JSONB)
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the trait was created
      type: object
      required:
      - id
      - agent_id
      - name
      - data_type
      - created_at
      title: CustomerTraitResponse
      description: Response model for customer trait operations.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GenerateTraitValuesRequest:
      properties:
        scenarios:
          items:
            type: string
          type: array
          title: Scenarios
          description: List of intents (one per scenario) to generate values for
        traits:
          items:
            $ref: '#/components/schemas/TraitInput'
          type: array
          title: Traits
          description: List of traits (name + data_type) to generate values for
        agent_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Prompt
          description: Optional agent description for context
        knowledge_base:
          anyOf:
          - type: string
          - type: 'null'
          title: Knowledge Base
          description: Optional knowledge base text for context
      type: object
      required:
      - scenarios
      - traits
      title: GenerateTraitValuesRequest
      description: 'Request: list of scenarios and list of traits; values are generated per scenario per trait.'
    UpdateCustomerTraitRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the trait
        data_type:
          anyOf:
          - $ref: '#/components/schemas/TraitDataType'
          - type: 'null'
          description: Data type of the trait
        default_value:
          anyOf:
          - {}
          - type: 'null'
          title: Default Value
          description: Default value for this trait (will be converted based on data_type)
      type: object
      title: UpdateCustomerTraitRequest
      description: Request model for updating a customer trait definition.
    CreateCustomerTraitRequest:
      properties:
        agent_id:
          type: integer
          title: Agent Id
          description: ID of the agent this trait belongs to
        name:
          type: string
          title: Name
          description: Name of the trait
        data_type:
          $ref: '#/components/schemas/TraitDataType'
          description: Data type of the trait
        default_value:
          anyOf:
          - {}
          - type: 'null'
          title: Default Value
          description: Default value for this trait (will be converted based on data_type)
      type: object
      required:
      - agent_id
      - name
      - data_type
      title: CreateCustomerTraitRequest
      description: Request model for creating a customer trait definition.
    CustomerTraitsListResponse:
      properties:
        traits:
          items:
            $ref: '#/components/schemas/CustomerTraitResponse'
          type: array
          title: Traits
          description: List of customer traits
        total_count:
          type: integer
          title: Total Count
          description: Total number of traits
      type: object
      required:
      - traits
      - total_count
      title: CustomerTraitsListResponse
      description: Response model for listing customer traits.
    TraitInput:
      properties:
        name:
          type: string
          title: Name
          description: Name of the trait
        data_type:
          $ref: '#/components/schemas/TraitDataType'
          description: Data type of the trait (BOOLEAN, STRING, NUMBER, DATE)
      type: object
      required:
      - name
      - data_type
      title: TraitInput
      description: One trait to generate values for.
    TraitDataType:
      type: string
      enum:
      - BOOLEAN
      - STRING
      - DATE
      - NUMBER
      title: TraitDataType
      description: Enum for trait data types.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key required to authenticate requests.