openapi: 3.1.0
info:
  title: Bluejay Agents Call Logs API
  description: Bluejay API
  version: 0.1.0
servers:
- url: https://api.getbluejay.ai
  description: Production server
security:
- apiKeyAuth: []
tags:
- name: Call Logs
paths:
  /v1/retrieve-call-logs:
    get:
      tags:
      - Call Logs
      summary: Retrieve Call Logs Index
      operationId: retrieve_call_logs_index_v1_retrieve_call_logs_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
  /v1/retrieve-call-logs/{agent_id}:
    get:
      tags:
      - Call Logs
      summary: Retrieve Call Logs
      description: 'Retrieve call logs for a specific agent given the agent ID.

        Returns a list of call objects, each with an additional "evaluations" field

        containing a list of evaluations joined via call_id.'
      operationId: retrieve_call_logs_v1_retrieve_call_logs__agent_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: label
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Label of the agent to filter by
          title: Label
        description: Label of the agent to filter by
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max calls per page
          default: 20
          title: Page Size
        description: Max calls per page
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: last
        in: query
        required: false
        schema:
          enum:
          - 1day
          - 3days
          - 7days
          - 30days
          - 90days
          - all
          type: string
          description: Last X days to filter by
          default: 1day
          title: Last
        description: Last X days to filter by
      - 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/RetrieveCallLogsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/retrieve-call-log:
    get:
      tags:
      - Call Logs
      summary: Retrieve Call Log Index
      operationId: retrieve_call_log_index_v1_retrieve_call_log_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
  /v1/retrieve-call-log/{call_id}:
    get:
      tags:
      - Call Logs
      summary: Retrieve Call Log
      description: 'Retrieve call logs for a specific agent given the agent ID.

        Returns a list of call objects, each with an additional "evaluations" field

        containing a list of evaluations joined via call_id.'
      operationId: retrieve_call_log_v1_retrieve_call_log__call_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call 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/RetrieveCallLogResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/call-log:
    delete:
      tags:
      - Call Logs
      summary: Delete Call Log Index
      operationId: delete_call_log_index_v1_call_log_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
        description: API key required to authenticate requests.
  /v1/call-log/{call_id}:
    delete:
      tags:
      - Call Logs
      summary: Delete Call Log
      description: "Delete a specific call log given its ID.\nValidates that the user has access to the call log by checking organization membership.\n\nArgs:\n    call_id: The ID of the call to delete\n    recording_only: If True, only delete the recording file and clear recording fields.\n                   If False (default), delete the entire call log."
      operationId: delete_call_log_v1_call_log__call_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: recording_only
        in: query
        required: false
        schema:
          type: boolean
          description: If true, only delete the recording file and clear recording fields. If false, delete the entire call log including all data.
          default: false
          title: Recording Only
        description: If true, only delete the recording file and clear recording fields. If false, delete the entire call log including all data.
      - 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/DeleteCallLogResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/call-logs:
    delete:
      tags:
      - Call Logs
      summary: Bulk Delete Call Logs
      description: "Delete multiple call logs given their IDs.\nValidates that the user has access to all call logs by checking organization membership.\n\nArgs:\n    body: Request body containing a list of call IDs to delete"
      operationId: bulk_delete_call_logs_v1_call_logs_delete
      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/BulkDeleteCallLogsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteCallLogsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/update-log/{call_id}:
    put:
      tags:
      - Call Logs
      summary: Update Log
      description: Update a specific call log given its ID.
      operationId: update_log_v1_update_log__call_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call 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/UpdateCallLogRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLogResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UpdateCallLogRequest:
      properties:
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
          description: List of tool calls to update
        events:
          anyOf:
          - items:
              $ref: '#/components/schemas/Event'
            type: array
          - type: 'null'
          title: Events
          description: List of events to update
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Metadata to update
        reevaluate:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Reevaluate
          description: Whether to reevaluate the log
          default: false
      type: object
      title: UpdateCallLogRequest
    DeleteCallLogResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        status:
          type: string
          title: Status
          description: Status of the response
          default: '200'
      type: object
      required:
      - message
      title: DeleteCallLogResponse
    Event:
      properties:
        title:
          type: string
          title: Title
          description: Title of the event
        start_offset_ms:
          type: integer
          title: Start Offset Ms
          description: Start offset of the event in milliseconds
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the event
        end_offset_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: End Offset Ms
          description: End offset of the event in milliseconds
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: List of tags associated with the event
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Additional metadata associated with the event
      type: object
      required:
      - title
      - start_offset_ms
      title: Event
      description: Pydantic model for event data
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetrieveCallLogsResponse:
      properties:
        call_logs:
          items:
            $ref: '#/components/schemas/CallLog'
          type: array
          title: Call Logs
          description: List of calls retrieved from the database
        total_count:
          type: integer
          title: Total Count
          description: Total number of calls for this agent
        page:
          type: integer
          title: Page
          description: Current page (1-based)
        page_size:
          type: integer
          title: Page Size
          description: Page size
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages
      type: object
      required:
      - total_count
      - page
      - page_size
      - total_pages
      title: RetrieveCallLogsResponse
    RetrieveCallLogResponse:
      properties:
        call_log:
          $ref: '#/components/schemas/CallLog'
          description: Details of the retrieved call log
        status:
          type: string
          title: Status
          description: Status of the response
          default: '200'
      type: object
      required:
      - call_log
      title: RetrieveCallLogResponse
    CallLog:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the call
        agent_id:
          type: string
          title: Agent Id
          description: ID of the agent associated with the call
        external_agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Agent Id
          description: External ID of the agent associated with the call
        recording_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Recording Url
          description: 'URL to the recording file (supported formats: .mp4, .wav, .m4a)'
        start_time_utc:
          type: string
          title: Start Time Utc
          description: When the call started, in UTC
        participants:
          items:
            $ref: '#/components/schemas/ParticipantResponse'
          type: array
          title: Participants
          description: List of call participants
        call_direction:
          $ref: '#/components/schemas/CallDirection'
          description: Direction of the call from the Agent's perspective (INBOUND or OUTBOUND)
          default: INBOUND
        interface:
          $ref: '#/components/schemas/CallInterface'
          description: Interface used for the call
          default: PHONE
        status:
          $ref: '#/components/schemas/CallStatus'
          description: Current status of the call
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When this request was created (defaults to now in UTC)
        transcript_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Transcript Url
          description: 'URL to the transcript file (supported formats: .txt, .json)'
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
          description: List of tool calls made during the call
        events:
          anyOf:
          - items:
              $ref: '#/components/schemas/Event'
            type: array
          - type: 'null'
          title: Events
          description: List of events that occurred during the call
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: List of tags associated with the call
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: Duration of the call in milliseconds
          default: 0
        evaluations:
          anyOf:
          - items:
              $ref: '#/components/schemas/Evaluation'
            type: array
          - type: 'null'
          title: Evaluations
          description: List of evaluations associated with the call
        annotations:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Annotations
          description: Annotations associated with the call
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Additional metadata associated with the call
        custom_metrics:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Custom Metrics
          description: Please use the custom metrics in the evaluations instead
          deprecated: true
        conversation_ended_by:
          anyOf:
          - $ref: '#/components/schemas/ParticipantRole'
          - type: 'null'
          description: 'Which participant role ended the conversation: ''USER'' or ''AGENT'''
      type: object
      required:
      - id
      - agent_id
      - recording_url
      - start_time_utc
      - participants
      - status
      title: CallLog
    CallInterface:
      type: string
      enum:
      - PHONE
      - WEB
      title: CallInterface
      description: Enum representing the interface used for a call.
    BulkDeleteCallLogsRequest:
      properties:
        call_ids:
          items:
            type: string
          type: array
          title: Call Ids
          description: List of call IDs to delete
      type: object
      required:
      - call_ids
      title: BulkDeleteCallLogsRequest
    BulkDeleteCallLogsResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        deleted_count:
          type: integer
          title: Deleted Count
          description: Number of calls successfully deleted
        status:
          type: string
          title: Status
          description: Status of the response
          default: '200'
      type: object
      required:
      - message
      - deleted_count
      title: BulkDeleteCallLogsResponse
    FillerIgnoredLatency:
      properties:
        avg_filler_ignored_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Filler Ignored Latency
          description: Average filler ignored latency
          default: 0
        p50_filler_ignored_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P50 Filler Ignored Latency
          description: 50th percentile filler ignored latency
          default: 0
        p90_filler_ignored_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P90 Filler Ignored Latency
          description: 90th percentile filler ignored latency
          default: 0
        p95_filler_ignored_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P95 Filler Ignored Latency
          description: 95th percentile filler ignored latency
          default: 0
        p99_filler_ignored_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P99 Filler Ignored Latency
          description: 99th percentile filler ignored latency
          default: 0
      type: object
      title: FillerIgnoredLatency
    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
    ParticipantRole:
      type: string
      enum:
      - AGENT
      - USER
      title: ParticipantRole
      description: Enum representing the role of a participant in a call.
    Latency:
      properties:
        avg_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Agent Latency
          description: Average latency
          default: 0
        max_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Agent Latency
          description: Maximum latency
          default: 0
        p50_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P50 Agent Latency
          description: 50th percentile latency
          default: 0
        p90_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P90 Agent Latency
          description: 90th percentile latency
          default: 0
        p95_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P95 Agent Latency
          description: 95th percentile latency
          default: 0
        p99_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: P99 Agent Latency
          description: 99th percentile latency
          default: 0
      type: object
      title: Latency
    UpdateLogResponse:
      properties:
        message:
          type: string
          title: Message
          description: Success message
        status:
          type: string
          title: Status
          description: Status of the response
          default: '200'
      type: object
      required:
      - message
      title: UpdateLogResponse
    CallStatus:
      type: string
      enum:
      - INITIALIZING
      - QUEUED
      - EVALUATING
      - COMPLETED
      - INCOMPLETED
      title: CallStatus
      description: Enum representing the possible states of a call.
    ParticipantResponse:
      properties:
        role:
          $ref: '#/components/schemas/ParticipantRole'
          description: Role of the participant in the call
        spoke_first:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Spoke First
          description: Whether the participant spoke first in the call
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the participant
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
          description: Phone number of the participant (if applicable)
      type: object
      required:
      - role
      title: ParticipantResponse
      description: Pydantic model for participant data
    src__models__api_custom_metric__CustomMetric:
      properties:
        name:
          type: string
          title: Name
          description: The name of the custom metric
        description:
          type: string
          title: Description
          description: The description of the custom metric
        response_type:
          type: string
          title: Response Type
          description: The response type of the custom metric
        response_value:
          type: string
          title: Response Value
          description: The response value of the custom metric
        reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning
          description: The reasoning of the custom metric
        min_value:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Value
          description: The minimum value of the custom metric
        max_value:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Value
          description: The maximum value of the custom metric
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: The category of the custom metric
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: The tags of the custom metric
        scoring_guidance:
          anyOf:
          - type: string
          - type: 'null'
          title: Scoring Guidance
          description: The scoring guidance of the custom metric
        enum_options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enum Options
          description: The enum options of the custom metric
      type: object
      required:
      - name
      - description
      - response_type
      - response_value
      title: Custom Metric
    CallDirection:
      type: string
      enum:
      - INBOUND
      - OUTBOUND
      title: CallDirection
      description: Enum representing the direction of a call.
    Evaluation:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the evaluation result
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When this evaluation result was created (defaults to now in UTC)
        hallucination:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hallucination
          description: Whether the agent exhibited hallucination during the call
        hallucination_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Hallucination Reasoning
          description: Reasoning behind the hallucination, if applicable
        redundancy:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Redundancy
          description: Whether the agent exhibited redundancy during the call
        redundancy_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Redundancy Reasoning
          description: Reasoning behind the redundancy, if applicable
        agent_speak_percentage:
          anyOf:
          - type: number
          - type: 'null'
          title: Agent Speak Percentage
          description: Percentage of the call where the agent was speaking
        avg_agent_latency:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Agent Latency
          description: Average latency of the agent's responses during the call
        latency:
          anyOf:
          - $ref: '#/components/schemas/Latency'
          - type: 'null'
          description: Latency metrics for the agent's responses
        filler_ignored_latency:
          anyOf:
          - $ref: '#/components/schemas/FillerIgnoredLatency'
          - type: 'null'
          description: Filler ignored latency metrics
        num_turns:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Turns
          description: Total number of turns taken by the agent during the call
        call_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Summary
          description: Summary of the call, if applicable
        custom_evals:
          anyOf:
          - items: {}
            type: array
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Custom Evals
          description: List of custom evaluations performed during the call
        custom_evals_success_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Custom Evals Success Rate
          description: Success rate of the custom evaluations performed during the call
        goal_success:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Goal Success
          description: Whether the goal was successfully achieved during the call
        goal_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Goal Reasoning
          description: Reasoning behind the goal success, if applicable
        pronunciation_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Pronunciation Score
          description: Pronunciation score of the agent during the call
        pronunciation_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Pronunciation Reasoning
          description: Reasoning behind the pronunciation score, if applicable
        custom_metrics:
          anyOf:
          - items:
              $ref: '#/components/schemas/src__models__api_custom_metric__CustomMetric'
            type: array
          - type: 'null'
          title: Custom Metrics
          description: Custom metrics associated with the evaluation
      type: object
      required:
      - agent_speak_percentage
      - avg_agent_latency
      title: Evaluation
      description: Pydantic model for evaluation result
    ToolCall:
      properties:
        name:
          type: string
          title: Name
          description: Name of the tool called
        start_offset_ms:
          type: integer
          minimum: 0.0
          title: Start Offset Ms
          description: Start offset of the tool call in milliseconds
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the tool call
        parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parameters
          description: Parameters passed to the tool call
        output:
          anyOf:
          - {}
          - type: 'null'
          title: Output
          description: Output returned by the tool call
      type: object
      required:
      - name
      - start_offset_ms
      title: ToolCall
      description: Represents a tool call during a conversation.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key required to authenticate requests.