API Foundations

Centralised reference for cross‑cutting details that apply to every Voilo REST endpoint.

Base URLs

Environment	Root URL	Key scope
Production	`https://api.voilo.io`	accepts live keys only
Sandbox	`https://api.sandbox.voilo.com`	accepts sandbox keys only

Voilo uses API keys passed via the Authorization header. API keys are generated and managed in the Platform Console (Settings → API Keys).

Secret keys are environment‑scoped: test keys start with sk_test_ and live keys start with sk_live_.

Authorization: Bearer <api_key>
Content-Type: application/json

Sandbox keys are rejected on the production host (and vice‑versa) with 401 invalid_auth.

Endpoints that return collections use cursor‑based pagination.

Query parameters:

Name	Type	Description
`cursor`	string, optional	ID from the previous response's `next_cursor`.
`limit`	integer, optional	Max items per page (default = 20, max = 100).

Example response snippet:

{
  "data": [ /* items */ ],
  "next_cursor": "MjAyNS0wNi0xMFQxNDo1MDozMFo",
  "has_more": true
}

Every non‑2xx response uses the same wrapper:

{
  "error": {
    "code": "invalid_auth",
    "message": "API key expired"
  }
}

Common Codes:

HTTP	`error.code`	Typical trigger
400	`bad_request`	Malformed JSON, missing field
401	`invalid_auth`	Missing/invalid key
403	`forbidden`	Key lacks permission
404	`not_found`	Resource or path absent
422	`validation_error`	Field violates business rule
500	`internal_error`	Unexpected server error

These topics will be documented here soon - shout if you need them sooner!