openapi: 3.0.3
info:
  title: Voximate Public API
  version: 0.1.0
  description: |
    Partner-facing HTTP API. Base URL is the gateway, not the dashboard.

    Authentication is `Authorization: Bearer <token>`. Today the gateway
    verifies a user JWT (`POST /auth/v1/login`). Tenant API keys (`vox_live_…`)
    are created under Settings and are the intended machine credential; accepting
    them on the gateway is the next auth change.

    This file matches **gateway prefixes that exist in code**, not the unused
    `/v1/agents` table from an older PRD.
  contact:
    email: kontakt@voximate.no
servers:
  - url: https://api.voximate.no
    description: Production
paths:
  /health:
    get:
      summary: Gateway liveness
      security: []
      responses:
        '200':
          description: Process is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: api-gateway
  /auth/v1/login:
    post:
      summary: Exchange email and password for a JWT
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        '200':
          description: Access and refresh tokens
        '401':
          description: Invalid credentials
  /agents:
    get:
      summary: List voice agents for the tenant
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: limit
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: Paginated agents
        '401':
          description: Missing or invalid Bearer token
    post:
      summary: Create an agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                description: { type: string }
                systemPrompt: { type: string }
      responses:
        '201':
          description: Created
  /agents/{agentId}:
    get:
      summary: Get one agent
      parameters:
        - in: path
          name: agentId
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Agent
        '404':
          description: Not found
  /analytics/calls:
    get:
      summary: List stored calls
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: limit
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Paginated calls
  /analytics/calls/{callId}:
    get:
      summary: Call detail
      parameters:
        - in: path
          name: callId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Call
  /v1/calls:
    post:
      summary: Start an outbound call
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [agent_id, to_number]
              properties:
                agent_id: { type: string, format: uuid }
                to_number: { type: string, example: '+4722405104' }
      responses:
        '200':
          description: Call accepted
        '429':
          description: Quota exceeded
  /phone-numbers:
    get:
      summary: List tenant phone numbers
      responses:
        '200':
          description: Numbers
  /v1/knowledge-bases:
    get:
      summary: List knowledge bases
      responses:
        '200':
          description: Knowledge bases
  /v1/tools:
    get:
      summary: List registered agent tools
      responses:
        '200':
          description: Tools
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []