VInfer AI REST API — Overview, Auth, and Error Codes

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.

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.

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.

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:

{
  "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:

{
  "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:

{
  "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.

Authentication

Generate an API key and learn how to include it in every request.

Campaigns

Create and manage outbound calling campaigns with Neuron.

Transcription

Submit call recordings to NeuronLens for transcription and analysis.

Overview

Neuron API

NeuronLens API

VInfer AI REST API — Overview, Auth, and Error Codes

Base URL

Request Format

Idempotency

Rate Limits

HTTP Status Codes

Error Format

Quick Navigation

Authentication

Campaigns

Transcription

Webhooks

​Base URL

​Request Format

​Idempotency

​Rate Limits

​HTTP Status Codes

​Error Format

​Quick Navigation

Authentication

Campaigns

Transcription

Webhooks

Base URL

Request Format

Idempotency

Rate Limits

HTTP Status Codes

Error Format

Quick Navigation