API reference

The Voicegram public API lets you integrate Voicegram with Zapier, Make, n8n, or any custom system. All requests authenticate via a Personal Access Token (PAT) sent in the Authorization: Bearer vg_pat_<...> header.

Base URL

https://www.voicegram.io

All paths in this reference are relative to that base URL. For example, GET /api/v1/me is https://www.voicegram.io/api/v1/me.

Authentication

Create a personal access token at Dashboard, Integrations, API access. The token authenticates every endpoint in this reference and works from curl, Make, n8n, Zapier, or your own backend.

Tokens are bound to a single account and inherit that account's permissions. The token format is vg_pat_ followed by 64 hexadecimal characters.

Voicegram never stores the plaintext after creation: tokens are therefore unrecoverable. If you lose a token, revoke it from the dashboard and create a new one.

Pass the token in the Authorization header on every request:

Authorization: Bearer vg_pat_<your-64-hex-token>

Plan gating

All endpoints except GET /api/v1/me require a paid plan (Starter or above). PATs for free-plan accounts authenticate successfully against /me so integrations can display a meaningful upgrade prompt, but every other endpoint returns 403 plan_required.

Rate limits

Each endpoint allows 60 requests per minute per account. The limit is enforced after authentication and authorization, so:

• Anonymous callers always see 401, never 429.
• Free-plan callers always see 403 plan_required, never 429.
• Only authenticated, paid-plan callers can ever see 429 rate_limited.

Errors

All errors share the same JSON envelope. The error field carries a stable enum code suitable for client diagnostics; message is human-readable and may change wording between releases. The optional issues array surfaces Zod schema errors and only appears on validation_error responses.

{
  "error": "validation_error",
  "message": "Body failed schema validation.",
  "issues": [
    {
      "path": [
        "url"
      ],
      "message": "Invalid url"
    }
  ]
}

Status codes

Error enum

The full list of stable error values returned by any endpoint:

• invalid_token
• plan_required
• validation_error
• invalid_url
• invalid_channel_id
• not_found
• rate_limited
• limit_reached
• conflict
• internal_error

Endpoints

Each endpoint has its own page with the full schema, parameters, example request, and per-status response shapes.

Account

• GET /api/v1/me: Get the authenticated account

Channels

• GET /api/v1/channels: List domains and campaigns

Voicegrams

• GET /api/v1/voicegrams/recent: List recent completed voicegrams

Webhooks

• GET /api/v1/webhook-subscriptions: List webhook subscriptions
• POST /api/v1/webhook-subscriptions: Create a webhook subscription
• GET /api/v1/webhook-subscriptions/{id}: Get a single webhook subscription
• DELETE /api/v1/webhook-subscriptions/{id}: Soft-delete a webhook subscription