openapi: 3.2.0
info:
  title: DialNexa LL Ms API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
- url: https://api.dialnexa.com
  description: DialNexa production API
security:
- bearer: []
tags:
- name: LLMs
paths:
  /v1/llms:
    get:
      operationId: listLlms
      parameters:
      - name: page
        required: false
        in: query
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        schema:
          example: 20
          type: number
      - name: sortBy
        required: false
        in: query
        schema:
          example: id
          type: string
      - name: sortOrder
        required: false
        in: query
        schema:
          enum:
          - ASC
          - DESC
          type: string
      responses:
        '200':
          description: LLMs returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Llm'
              examples:
                success:
                  summary: Successful response
                  value:
                  - id: llm_A1B2C3D4E5F6G7
                    name: GPT-4.1 Mini
                    provider: openai
                    supports_structured_output: true
        '400':
          description: Bad request - invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid query parameters
                    error: Bad Request
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
        '403':
          description: Forbidden - API key does not have access to this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
      security:
      - bearer: []
      summary: List LLMs
      tags:
      - LLMs
      description: Returns the complete catalog of large language models available for agent configuration.
  /v1/llms/fallback:
    get:
      operationId: listFallbackLlms
      parameters:
      - name: page
        required: false
        in: query
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        schema:
          example: 20
          type: number
      - name: sortBy
        required: false
        in: query
        schema:
          example: id
          type: string
      - name: sortOrder
        required: false
        in: query
        schema:
          enum:
          - ASC
          - DESC
          type: string
      responses:
        '200':
          description: Fallback LLM returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Llm'
              examples:
                success:
                  summary: Successful response
                  value: []
        '400':
          description: Bad request - invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid query parameters
                    error: Bad Request
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
        '403':
          description: Forbidden - API key does not have access to this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
      security:
      - bearer: []
      summary: List Fallback LLMs
      tags:
      - LLMs
      description: Returns large language models that can be selected as fallback models.
  /v1/llms/{id}:
    get:
      operationId: getLlm
      parameters:
      - name: id
        required: true
        in: path
        description: LLM ID
        schema:
          example: llm_abc123
          type: string
      responses:
        '200':
          description: LLM returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Llm'
              examples:
                success:
                  summary: Successful response
                  value:
                    id: llm_A1B2C3D4E5F6G7
                    name: GPT-4.1 Mini
                    provider: openai
                    supports_structured_output: true
        '400':
          description: Invalid catalog ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid catalog ID format
                    error: Bad Request
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '404':
          description: LLM not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: LLM not found
                    error: Not Found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
        '403':
          description: Forbidden - API key does not have access to this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
      security:
      - bearer: []
      summary: Get LLM Details
      tags:
      - LLMs
      description: Returns one large language model catalog record by ID.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          example: phone_number must be a valid E.164 phone number
        error:
          type: string
          example: Bad Request
      required:
      - statusCode
      - message
      - error
    Llm:
      type: object
      properties:
        id:
          type: string
          example: llm_abc123
          description: Signed LLM ID
      required:
      - id
  securitySchemes:
    bearer:
      scheme: bearer
      type: http