InfiVoice Introduction API

openapi: 3.2.0
info:
  title: InfiVoice REST Introduction 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: Introduction
  description: 'InfiVoice provides a powerful REST API for automating AI-powered voice calls. Whether you''re building customer outreach, appointment reminders, lead qualification, or interactive voice applications, our API gives you full control.


    ---


    Navigate to your InfiVoice dashboard → API Keys page (left sidebar, /app/api-keys) to create an API key. Keep this key secure—it provides full access to your account.


    Test your connection with a simple health check:


    ```bash

    curl -X GET "https://infivoice.com/api/v1/health"

    ```


    Include your API key in every request using one of these methods:


    ```bash

    curl -H "Authorization: Bearer YOUR_API_KEY" ...


    curl -H "X-API-Key: YOUR_API_KEY" ...

    ```


    ---


    | Concept | Description |

    |---------|-------------|

    | **Agents** | AI voice agents that handle conversations. Two types: Flow (visual conversation builder) and Incoming (for inbound calls). |

    | **Campaigns** | Bulk calling operations targeting multiple contacts with the same agent. |

    | **Calls** | Individual voice call records with transcripts, recordings, and analytics. |

    | **Contacts** | Your CRM leads with phone numbers, custom fields, and AI-enriched data. |

    | **Credits** | Billing units where 1 credit = 1 minute of call time. |

    | **Webhooks** | Real-time event notifications delivered to your endpoints. |


    ---


    InfiVoice supports three telephony engines for different use cases:


    | Engine | AI Provider | Best For |

    |--------|-------------|----------|

    | `elevenlabs` | ElevenLabs Conversational AI | High-quality voices, 29 languages |

    | `plivo` | OpenAI Realtime API | India and APAC regions |

    | `twilio-openai` | OpenAI Realtime API | Global coverage, reliable routing |


    ---


    All API endpoints (except `/health`) require authentication. Include your API key in every request:


    - **Authorization Header**: `Authorization: Bearer YOUR_API_KEY`

    - **X-API-Key Header**: `X-API-Key: YOUR_API_KEY`


    API keys have scoped permissions. Ensure your key has the required scopes for the endpoints you''re accessing.


    ---


    Requests are rate-limited based on your subscription plan:


    | Plan | Limit |

    |------|-------|

    | Free | 60 requests/minute |

    | Pro | 300 requests/minute |

    | Enterprise | 1000 requests/minute |


    **Rate limit headers in responses:**


    - `X-RateLimit-Limit` — Maximum requests per window

    - `X-RateLimit-Remaining` — Remaining requests

    - `X-RateLimit-Reset` — Unix timestamp when window resets


    ---


    ```json

    {

    "success": true,

    "data": { ... },

    "meta": {

    "requestId": "uuid",

    "timestamp": "2024-01-01T00:00:00.000Z"

    }

    }

    ```


    ```json

    {

    "success": false,

    "error": {

    "code": "ERROR_CODE",

    "message": "Human readable message",

    "details": { ... }

    },

    "meta": { ... }

    }

    ```


    ---


    | Code | HTTP Status | Description |

    |------|-------------|-------------|

    | `VALIDATION_ERROR` | 400 | Invalid request parameters |

    | `UNAUTHORIZED` | 401 | Missing or invalid API key |

    | `FORBIDDEN` | 403 | Insufficient permissions |

    | `NOT_FOUND` | 404 | Resource not found |

    | `INSUFFICIENT_CREDITS` | 402 | Not enough credits |

    | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |'
paths:
  /health:
    get:
      summary: Health Check
      description: 'Verify the API is operational. This endpoint does not require authentication and is useful for monitoring and uptime checks.


        **Use Case:** Add this endpoint to your monitoring tools to detect API outages.'
      operationId: healthCheck
      tags:
      - Introduction
      security: []
      responses:
        '200':
          description: API is healthy and ready to accept requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
components:
  schemas:
    HealthResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            status:
              type: string
              example: healthy
            version:
              type: string
              example: v1
            timestamp:
              type: string
              format: date-time
  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)