Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.masker.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Masker REST API is the same API that powers the portal. Anything you can do in the UI you can do over HTTP — create agents, list sessions, download compliance reports, and integrate the proxy into your voice pipeline. This page covers the conventions that apply to every endpoint.

​
Base URL

https://masker-voice.fly.dev/api/v1
For self-hosted deployments, replace the hostname with your own. All paths below are relative to this base URL unless noted otherwise. A small number of endpoints sit outside /api/v1 because they’re called by external systems with their own URL conventions:
EndpointPurpose
POST /proxy/{agent_id}/v1/chat/completionsOpenAI-compatible LLM proxy called by your voice platform
POST /vapi/webhook/{agent_id}Vapi assistant-request webhook
GET /healthHealth check

​
Conventions

  • JSON only. All request and response bodies are application/json unless the endpoint explicitly returns another content type (e.g. application/pdf for report downloads).
  • UTF-8. All strings are UTF-8 encoded.
  • ISO 8601 UTC for all timestamps — for example, 2026-05-03T21:14:32.481Z.
  • ULIDs for resource IDs, prefixed by resource type: agt_01HYZ... for agents, sess_01HYZ... for sessions, evt_01HYZ... for events.
  • Snake_case for all request and response field names.
  • Meaningful HTTP status codes. 2xx means success, 4xx means a problem with your request, 5xx means a problem on our end.

​
Pagination

All list endpoints use cursor-based pagination. Pass limit and cursor as query parameters: 
curl "https://masker-voice.fly.dev/api/v1/sessions?limit=50&cursor=eyJ..."
​
limit
number
default:"25"
Maximum number of results to return. Accepted range: 1–100.
​
cursor
string
Opaque pagination cursor returned in the previous response as next_cursor. Omit to start from the beginning.
Every list response includes next_cursor. When it is null or absent, you have reached the last page: 
{
  "data": [...],
  "next_cursor": "eyJ..."
}
Pass the value of next_cursor as cursor on the next request to retrieve the following page.

​
Errors

All errors use a standard envelope: 
{
  "error": {
    "code": "agent_not_found",
    "message": "No agent with id agt_01HYZ...",
    "request_id": "req_01HYZ..."
  }
}
Always log the request_id — it is the fastest way to diagnose an issue when contacting support.
CodeHTTP statusMeaning
unauthenticated401No valid masker_session cookie
forbidden403Authenticated but not permitted for this action
not_found404Resource does not exist or is not visible to your account
validation_failed422Request body or query parameter failed validation
rate_limited429Too many requests; respect the Retry-After response header
upstream_error502The upstream LLM provider returned an error
internal_error500An error on our end; include request_id when reporting

​
Rate limits

The hosted service enforces per-account limits:
Endpoint groupSustained limitBurst limit
/proxy/* and /vapi/webhook/*100 req/s200 req/s
All other /api/v1/* endpoints30 req/s60 req/s
When you are rate-limited, the API returns 429 with a Retry-After header specifying how many seconds to wait before retrying. Self-hosted deployments have no rate limit applied by default.

​
Versioning

The current API version is v1. Masker will not introduce breaking changes under v1. When v2 ships, both versions will run in parallel for at least six months before v1 is retired. Backwards-compatible changes — new endpoints, new optional request fields, new optional response fields, new enum values — are added to v1 without a version bump.

​
Authentication

Every /api/v1/* endpoint requires a valid masker_session cookie. See Authentication for how to obtain and use it. The proxy and webhook endpoints use a separate mechanism described on their respective pages.