Okareo Drivers API

openapi: 3.2.0
info:
  title: Okareo Drivers API
  version: 0.1.0
  description: Register and manage Drivers (simulated callers/users).
servers:
- url: https://api.okareo.com
tags:
- name: Drivers
  description: Register and manage Drivers (simulated callers/users).
paths:
  /v0/generate_driver_prompt:
    post:
      tags:
      - Drivers
      summary: Generate Driver Prompt
      operationId: generate_driver_prompt_v0_generate_driver_prompt_post
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverPromptRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverPromptResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/driver:
    post:
      tags:
      - Drivers
      summary: Register Driver Model
      operationId: register_driver_model_v0_driver_post
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverModelSchema'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/VoiceDriverModelResponse'
                - $ref: '#/components/schemas/DriverModelResponse'
                title: Response Register Driver Model V0 Driver Post
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/drivers:
    get:
      tags:
      - Drivers
      summary: Get All Drivers
      operationId: get_all_drivers_v0_drivers_get
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: The ID of the project
          title: Project Id
        description: The ID of the project
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                  - $ref: '#/components/schemas/VoiceDriverModelResponse'
                  - $ref: '#/components/schemas/DriverModelResponse'
                title: Response Get All Drivers V0 Drivers Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/driver/{identifier}:
    get:
      tags:
      - Drivers
      summary: Get Driver
      operationId: get_driver_v0_driver__identifier__get
      parameters:
      - name: identifier
        in: path
        required: true
        schema:
          type: string
          title: Identifier
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/VoiceDriverModelResponse'
                - $ref: '#/components/schemas/DriverModelResponse'
                title: Response Get Driver V0 Driver  Identifier  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/driver/{driver_id}:
    put:
      tags:
      - Drivers
      summary: Update Driver Model
      operationId: update_driver_model_v0_driver__driver_id__put
      parameters:
      - name: driver_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Driver Id
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriverModelSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/VoiceDriverModelResponse'
                - $ref: '#/components/schemas/DriverModelResponse'
                title: Response Update Driver Model V0 Driver  Driver Id  Put
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Drivers
      summary: Delete Driver Model
      operationId: delete_driver_model_v0_driver__driver_id__delete
      parameters:
      - name: driver_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Driver Id
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '204':
          description: Successful Response
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/driver_profiles:
    get:
      tags:
      - Drivers
      summary: Get Driver Profiles
      description: 'Get the list of available voice profiles for driver models.


        Returns:

        List of voice profile names.'
      operationId: get_driver_profiles_v0_driver_profiles_get
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VoiceProfileResponse'
                title: Response Get Driver Profiles V0 Driver Profiles Get
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/driver_voices:
    get:
      tags:
      - Drivers
      summary: Get Driver Voices
      description: 'Get the list of available voices for driver models with metadata.


        Returns:

        List of voice dictionaries with:

        - id: Voice ID (UUID)

        - name: Full voice name (e.g., "Ray - Conversationalist", used when creating driver)

        - language: Language code (BCP-47 format)

        - gender: Gender ("feminine" or "masculine")

        - description: Voice description'
      operationId: get_driver_voices_v0_driver_voices_get
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response Get Driver Voices V0 Driver Voices Get
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/driver/test:
    post:
      tags:
      - Drivers
      summary: Test Driver Model
      description: 'Test a driver model by providing a test input prompt.

        Returns the text and optional voice response generated by the driver model.'
      operationId: test_driver_model_v0_driver_test_post
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestDriverRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestDriverResponse'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
      - detail
      title: ErrorResponse
    VoiceProfileResponse:
      properties:
        profile_name:
          type: string
          title: Profile Name
        voice_instructions:
          type: string
          title: Voice Instructions
      type: object
      required:
      - profile_name
      - voice_instructions
      title: VoiceProfileResponse
    TestDriverRequest:
      properties:
        prompt_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Template
          description: Prompt template for the driver model. If not provided, backend will generate one based on language parameter.
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: Temperature of the driver model
          default: 0
        voice_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Instructions
          description: Voice instructions for the driver model
        voice_profile:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Profile
          description: 'Voice profile for the driver model. Select from the following list of options: neutral, happy, excited, content, curious, calm, confident, surprised, confused, sad, disappointed, bored, frustrated, angry, agitated, anxious, scared, sarcastic.'
        voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice
          description: Voice setting for the driver model. Use GET /v0/voices to retrieve available voice options.
        voice_tone:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Tone
          description: Driver's emotion/tone passed to Cartesia (a canonical tone token). If omitted but voice_profile is set, it is derived from the profile.
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: Language code in BCP-47 format (e.g., 'en-US', 'es-MX', 'ja', 'fr-CA'). For voice targets, improves STT accuracy by constraining language model.
        test_input:
          type: string
          maxLength: 8000
          minLength: 1
          title: Test Input
          description: Test prompt to which the driver model will respond.
      type: object
      required:
      - test_input
      title: TestDriverRequest
    DriverModelSchema:
      properties:
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: ID of the driver model
        name:
          type: string
          title: Name
          description: Name of the driver model
        temperature:
          type: number
          title: Temperature
          description: Temperature of the driver model
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
          description: Model ID of the driver model
        prompt_template:
          type: string
          title: Prompt Template
          description: Prompt template for the driver model
        voice_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Instructions
          description: Voice instructions for the driver model
        voice_profile:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Profile
          description: 'Voice profile for the driver model. Select from the following list of options: neutral, happy, excited, content, curious, calm, confident, surprised, confused, sad, disappointed, bored, frustrated, angry, agitated, anxious, scared, sarcastic.'
        voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice
          description: Voice setting for the driver model. Use GET /v0/voices to retrieve available voice options.
        voice_tone:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Tone
          description: Driver's emotion/tone passed to Cartesia (a canonical tone token, e.g. 'happy', 'frustrated'). Definitive source of the driver's emotion. If omitted but voice_profile is set, it is derived from the profile.
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: Language code in BCP-47 format (e.g., 'en-US', 'es-MX', 'ja', 'fr-CA'). For voice targets, improves STT accuracy by constraining language model. If not specified, defaults to 'multi' for automatic language detection.
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
          description: ID for project
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: Tags are strings that can be used to filter drivers in the Okareo app. Omit to leave existing tags unchanged; send an empty list to clear them.
        steps:
          anyOf:
          - items:
              $ref: '#/components/schemas/DriverStepSchema'
            type: array
          - type: string
          - type: 'null'
          title: Steps
          description: 'Scripted Driver: an ordered list of steps ({message}, {dtmf}, {end_conversation}), or one {scenario_input.<column>} reference that resolves to that list per scenario row. end_conversation must be last. When set, prompt_template is not used and no Driver LLM runs.'
      type: object
      required:
      - name
      - temperature
      - prompt_template
      title: DriverModelSchema
    DriverStepSchema:
      properties:
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Words the Driver says, verbatim.
        dtmf:
          anyOf:
          - type: string
          - type: 'null'
          title: Dtmf
          description: 'Keys the Driver presses (0-9, A-D, *, #, w); voice only.'
        silence:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Silence
          description: 'true: the Driver says nothing this turn and listens for the Target''s next segment; voice only.'
        end_conversation:
          anyOf:
          - type: string
          - type: 'null'
          title: End Conversation
          description: Closing words; the Driver says them and ends the call.
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Why the script ended the call (with end_conversation only).
        turn:
          anyOf:
          - type: integer
          - type: 'null'
          title: Turn
          description: Reserved; rejected today.
      additionalProperties: false
      type: object
      title: DriverStepSchema
      description: 'One scripted step: exactly one of message / dtmf / end_conversation (checked by the

        steps validator), with an optional reason on end_conversation. Unknown keys are a 422.'
    DriverPromptResponse:
      properties:
        driver_prompt:
          type: string
          minLength: 1
          title: Driver Prompt
        suggested_name:
          type: string
          maxLength: 60
          minLength: 1
          title: Suggested Name
      additionalProperties: false
      type: object
      required:
      - driver_prompt
      - suggested_name
      title: DriverPromptResponse
    VoiceDriverModelResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        temperature:
          type: number
          title: Temperature
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
        prompt_template:
          type: string
          title: Prompt Template
        time_created:
          type: string
          title: Time Created
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
        is_predefined:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Predefined
          default: false
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
        steps:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: string
          - type: 'null'
          title: Steps
        voice_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Instructions
        voice:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice
        voice_tone:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Tone
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
      type: object
      required:
      - id
      - name
      - temperature
      - prompt_template
      - time_created
      title: VoiceDriverModelResponse
    TestDriverResponse:
      properties:
        text_response:
          type: string
          title: Text Response
          description: The text response generated by the driver model for the test input.
        voice_response:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Response
          description: The voice response generated by the driver model for the test input, if applicable. Encoded as a base64 string.
      type: object
      required:
      - text_response
      title: TestDriverResponse
    DriverModelResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        temperature:
          type: number
          title: Temperature
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
        prompt_template:
          type: string
          title: Prompt Template
        time_created:
          type: string
          title: Time Created
        project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Project Id
        is_predefined:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Predefined
          default: false
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
        steps:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: string
          - type: 'null'
          title: Steps
      type: object
      required:
      - id
      - name
      - temperature
      - prompt_template
      - time_created
      title: DriverModelResponse
    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
    DriverPromptRequest:
      properties:
        user_input:
          type: string
          maxLength: 8000
          title: User Input
          default: ''
        prior_prompt:
          anyOf:
          - type: string
            maxLength: 50000
          - type: 'null'
          title: Prior Prompt
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: BCP-47 language code (e.g., 'en', 'es', 'fr-CA', 'ja') for the driver prompt. Specifies what language the driver should always and only respond to. Defaults to 'en' (English) if not provided.
        voice_enabled:
          type: boolean
          title: Voice Enabled
          description: Whether the driver has voice enabled. When true, the generated prompt includes the spoken-delivery guidance ('When speaking (voice calls only)'); when false it is omitted.
          default: false
      additionalProperties: false
      type: object
      title: DriverPromptRequest