InfiVoice Credits API

openapi: 3.2.0
info:
  title: InfiVoice REST Credits API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Credits
  description: 'Monitor your credit balance and usage history. Credits are consumed during calls at a rate of 1 credit per minute.


    **Understanding Credits:**

    - Credits are deducted in real-time during calls

    - Partial minutes are rounded up

    - Campaigns pause automatically when credits run low

    - View historical usage for budgeting'
paths:
  /credits/balance:
    get:
      summary: Get Credit Balance
      description: 'Check your current credit balance. Use this to verify you have sufficient credits before starting campaigns.


        **Credit System:**

        - 1 credit = 1 minute of call time

        - Partial minutes are rounded up

        - Balance updates in real-time during calls


        **Required Scope:** `credits:read`'
      operationId: getCreditBalance
      tags:
      - Credits
      responses:
        '200':
          description: Current credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credits/usage:
    get:
      summary: Get Credit Usage
      description: 'Retrieve credit usage history for budgeting and analysis. Shows daily usage breakdown.


        **Use Cases:**

        - Track spending over time

        - Identify high-usage periods

        - Plan credit purchases

        - Generate billing reports


        **Required Scope:** `credits:read`'
      operationId: getCreditUsage
      tags:
      - Credits
      parameters:
      - name: days
        in: query
        description: Number of days to include in the report (default 30, max 90)
        schema:
          type: integer
          default: 30
          minimum: 1
          maximum: 90
      responses:
        '200':
          description: Daily credit usage breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditUsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    CreditBalanceResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            available:
              type: number
            reserved:
              type: number
            total:
              type: number
            currency:
              type: string
              example: credits
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
    CreditUsageResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            period:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                end:
                  type: string
                  format: date-time
            usage:
              type: array
              items:
                type: object
                properties:
                  date:
                    type: string
                    format: date
                  calls:
                    type: integer
                  minutes:
                    type: integer
                  credits:
                    type: number
            total:
              type: object
              properties:
                calls:
                  type: integer
                minutes:
                  type: integer
                credits:
                  type: number
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)