> ## Documentation Index
> Fetch the complete documentation index at: https://kb.vinfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# VInfer AI REST API — Overview, Auth, and Error Codes
> Complete REST API reference for VInfer AI — base URL, versioning, request format, rate limits, and error handling for Neuron and NeuronLens.
The VInfer AI REST API gives you programmatic access to every capability of the platform — from launching outbound voice campaigns and retrieving call records with **Neuron**, to submitting recordings for transcription, running QA scoring, and pulling aggregated analytics with **NeuronLens**. All resources are exposed over HTTPS, accept JSON request bodies, and return JSON responses, so you can integrate VInfer into any backend stack or workflow automation tool.
## Base URL
Every API request is made to the following base URL. The version segment (`v1`) is part of the path:
```
https://api.vinfer.ai/v1
```
Whenever a new version is released, the previous version remains available under its own path prefix, giving you time to migrate without breaking existing integrations.
## Request Format
For all `POST` and `PATCH` requests, set the `Content-Type` header to `application/json` and pass a JSON object as the request body. `GET` and `DELETE` requests use query parameters only — no request body is required.
```bash theme={null}
curl https://api.vinfer.ai/v1/campaigns \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Q1 Outreach", "script_id": "scr_abc123", "language": "hi-IN", "contacts": []}'
```
All timestamps in request bodies and responses use **ISO 8601** format (`2024-01-15T10:35:22Z`). All phone numbers use **E.164** format (`+919876543210`).
## Idempotency
For `POST` requests that create resources, you can include an `Idempotency-Key` header with a unique string (UUID recommended). If you retry a request with the same key within 24 hours, VInfer returns the original response instead of creating a duplicate resource — useful for safely retrying after network timeouts.
```bash theme={null}
curl https://api.vinfer.ai/v1/campaigns \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{"name": "Q1 Outreach", "script_id": "scr_abc123", "language": "hi-IN", "contacts": []}'
```
## Rate Limits
By default, your workspace is allowed **1,000 requests per minute** across all endpoints. If you exceed the limit, the API returns a `429 Too Many Requests` response. The response headers include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (Unix timestamp) so you can implement adaptive back-off in your client.
If your use case requires a higher rate limit — for example, a bulk data pipeline or real-time dashboard — contact VInfer support to request an increase for your workspace.
## HTTP Status Codes
The API uses standard HTTP status codes. Successful responses always carry a `2xx` code; client and server errors carry `4xx` and `5xx` codes respectively.
| Code | Meaning |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` | Request succeeded. Response body contains the requested data. |
| `201 Created` | Resource created successfully. Response body contains the new resource. |
| `202 Accepted` | Request accepted for asynchronous processing (e.g., transcription jobs). |
| `400 Bad Request` | One or more request parameters are missing or invalid. |
| `401 Unauthorized` | The `Authorization` header is missing, the key is invalid, or the key has been revoked. |
| `403 Forbidden` | Your API key is valid but does not have permission for the requested action. |
| `404 Not Found` | The resource with the given ID does not exist in your workspace. |
| `429 Too Many Requests` | You have exceeded the rate limit. Back off and retry after `X-RateLimit-Reset`. |
| `500 Internal Server Error` | An unexpected error occurred on VInfer's servers. These are rare — if they persist, check the [status page](https://status.vinfer.ai). |
## Error Format
Every error response — regardless of status code — returns a consistent JSON envelope. This makes it straightforward to handle errors programmatically without parsing free-form text.
**`invalid_parameter` — a request field value is missing, malformed, or out of range:**
```json theme={null}
{
"error": {
"code": "invalid_parameter",
"message": "The 'language' field must be a valid BCP-47 language code.",
"details": {
"field": "language",
"provided": "hindi",
"expected": "BCP-47 format, e.g. hi-IN"
}
}
}
```
**`resource_not_found` — the ID you referenced does not exist in your workspace:**
```json theme={null}
{
"error": {
"code": "resource_not_found",
"message": "Campaign 'cmp_unknownXYZ' does not exist or does not belong to your workspace.",
"details": {
"resource_type": "campaign",
"id": "cmp_unknownXYZ"
}
}
}
```
**`rate_limit_exceeded` — you have sent too many requests in the current window:**
```json theme={null}
{
"error": {
"code": "rate_limit_exceeded",
"message": "You have exceeded the request rate limit of 1000 requests per minute. Retry after the time indicated in X-RateLimit-Reset.",
"details": {
"limit": 1000,
"reset_at": "2024-02-01T09:15:00Z"
}
}
}
```
The `code` field is a machine-readable string you can use in conditional logic. The `message` field is a human-readable description suitable for logging. The `details` object provides additional context where available and may be omitted or empty (`{}`) for simpler errors.
## Quick Navigation
Generate an API key and learn how to include it in every request.
Create and manage outbound calling campaigns with Neuron.
Submit call recordings to NeuronLens for transcription and analysis.
Register endpoints to receive real-time call event notifications.