API Overview

The Voisnap REST API is organized around standard HTTP verbs and returns JSON-encoded responses. All API access is over HTTPS.

---

Base URL

https://api.voisnap.ai/api/v1

All endpoints in this reference are relative to this base URL unless noted otherwise.

---

Request format

Set the Content-Type header to application/json for all POST, PUT, and PATCH requests:

POST /api/v1/agents HTTP/1.1
Host: api.voisnap.ai
Authorization: Bearer vsnp_live_...
Content-Type: application/json
 
{
  "name": "My Agent"
}

---

Response format

All responses are JSON objects. Successful responses return the resource directly (for single-item requests) or a paginated envelope (for list requests).

Single resource:

{
  "id": "agt_01HXK8Z3MNPQRS",
  "name": "Aria – Support Agent",
  "status": "active",
  "createdAt": "2025-06-15T10:00:00Z"
}

List/paginated response:

{
  "data": [ ... ],
  "page": 1,
  "pageSize": 20,
  "total": 143,
  "totalPages": 8
}

---

Pagination

List endpoints support cursor-free page-based pagination:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
pageSize	integer	20	Items per page (max 100)
sortBy	string	varies	Field to sort by
sortOrder	string	desc	asc or desc

curl "https://api.voisnap.ai/api/v1/agents?page=2&pageSize=50&sortBy=createdAt&sortOrder=asc" \
  -H "Authorization: Bearer vsnp_live_..."

---

Error format

All errors follow RFC 7807 Problem Details:

{
  "type": "https://docs.voisnap.ai/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No agent with ID agt_01HXZZZ was found in your account.",
  "traceId": "trace_01HXMN8ZPQRST"
}

Field	Description
type	URI identifying the error type — links to documentation
title	Human-readable error title
status	HTTP status code
detail	Detailed explanation of the specific error
traceId	Unique request trace ID — include this when contacting support

Validation errors

For 422 responses, an additional errors array describes field-level validation failures:

{
  "type": "https://docs.voisnap.ai/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains invalid fields.",
  "traceId": "trace_01HXMN8ZPQRST",
  "errors": [
    {
      "field": "voice.provider",
      "message": "must be one of: elevenlabs, google, aws, azure"
    },
    {
      "field": "maxDurationSeconds",
      "message": "must be between 30 and 3600"
    }
  ]
}

---

HTTP status codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
204 No Content	Request succeeded with no response body (e.g., DELETE)
400 Bad Request	Malformed JSON or missing required parameters
401 Unauthorized	Missing, invalid, or expired authentication credentials
403 Forbidden	Valid credentials but insufficient permissions (missing scope)
404 Not Found	Resource does not exist or does not belong to your account
409 Conflict	Resource conflict (e.g., duplicate name, already assigned)
422 Unprocessable Entity	Request body is valid JSON but fails business rule validation
429 Too Many Requests	Rate limit exceeded — see Rate Limits
500 Internal Server Error	Unexpected server error — include traceId when reporting
503 Service Unavailable	Temporary service degradation — retry with backoff

---

Authentication headers

# API key
Authorization: Bearer vsnp_live_k8za1b2c3d4e5f6g7h8i9j0
 
# JWT access token
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

---

Idempotency

For POST requests that create resources or trigger actions, you can supply an idempotency key to safely retry without creating duplicates:

POST /api/v1/outbound-calls
Idempotency-Key: idem_your-unique-request-id-here

If a request with the same Idempotency-Key was processed within the last 24 hours, the original response is returned without re-executing the operation.

---

Common response headers

X-Request-Id: req_01HXMN8Z...
X-Api-Version: 1
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718445660
X-RateLimit-Policy: api-standard