Quickstart

Once you have a bearer token from your dashboard, confirm it works by hitting the /me endpoint. This is the simplest authenticated request and a good sanity check before building anything heavier. /me works with both public (pk_live_…) and private (sk_live_…) keys.

curl https://go.convoi.ai/backend/api/v1/public/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

{
  "user": { "id": "usr_…", "email": "you@example.com" },
  "key": {
    "id": "key_…",
    "name": "My CLI key",
    "type": "private",
    "created_at": "2026-05-01T10:00:00Z",
    "last_used_at": "2026-05-08T12:00:00Z"
  },
  "credits": { "remaining": 12.50, "currency": "USD" }
}

Calls always run against an agent. Fetch the list of agents on your account to grab an agent_id for the next step. No body and no query parameters required.

curl https://go.convoi.ai/backend/api/v1/public/agents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

To fetch a single agent, append its ID:

GET /api/v1/public/agents/agt_b88d642dd68747f28305c428b209xxxx

A web call returns a LiveKit URL and access token your frontend can use to join the call from a browser. The call begins as soon as a participant joins. Optionally pass an Idempotency-Key header (any random UUID) for 24-hour replay protection.

curl -X POST https://go.convoi.ai/backend/api/v1/public/calls \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c…-uuid" \
  -d '{
    "type": "web",
    "agent_id": "agt_b88d642dd68747f28305c428b209xxxx"
  }'

• Place outbound calls to phone numbers. See Calls → Outbound Phone Calls.
• Override an agent's prompt or voice per call. See Calls → Agent Overrides.
• Explore every endpoint interactively in the API Reference.