Documentation/API Reference

API Reference

The Vouchstone API is organized around REST principles. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

All API requests should be made to the following base URL:

https://www.vouchstone.ai/api/v1

Authentication

The Vouchstone API uses JWT Bearer tokens, not standalone API keys. Get a token from POST /api/v1/auth/login, then include it in the Authorization header of every request:

curl https://www.vouchstone.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Secure Your Access Tokens

Access tokens carry significant privileges. Do not share them in publicly accessible areas such as GitHub, client-side code, or public forums.

Rate Limits

Requests are rate-limited per client IP address using a sliding window, not by billing plan:

Scope	Requests/Minute
All other endpoints	120
Auth (login, register, forgot-password)	10
Heavy public endpoints (landing chat, voice TTS, intake drafts)	30

Exceeding a limit returns 429 Too Many Requests.

Response Format

Responses return the resource (or list) directly as JSON — there is no {success, data} envelope. A successful create/fetch looks like:

Successful Response

{
  "id": "agent_abc123",
  "name": "Customer Support Agent",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Response

Errors follow FastAPI's standard shape — a detail field, either a string or a list of field errors:

{
  "detail": "The agent name is required"
}

// Validation errors (422)
{
  "detail": [
    { "loc": ["body", "name"], "msg": "field required", "type": "value_error.missing" }
  ]
}