{"openapi":"3.1.0","info":{"title":"Voxlyn Public API","description":"Place and manage AI phone calls from your own software.\n\n## Authentication\nCreate a key in the dashboard under **Integrations → API keys** and send it on every request:\n\n    Authorization: Bearer vxk_live_…\n\nKeep it secret: use it only from your server. Each key has scopes (`read`, `calls`, `campaigns`) and can\nhave a monthly minute cap. A revoked key stops working within seconds.\n\n## Pricing and limits\nThere is no per-request fee. A call placed through the API uses your plan's minutes exactly like a call\nfrom the dashboard: included minutes first, then overage at your plan's rate up to the monthly overage cap\nyou set, and premium models or voices count 1.5 minutes per minute. A key's own monthly minute cap,\nwhen set, is enforced as well. Requests per minute (per key) and calls live at the same time (per\nworkspace) depend on your plan (`GET /usage`). Every response carries `X-RateLimit-Limit`,\n`X-RateLimit-Remaining` and `X-RateLimit-Reset`; a `429` carries `Retry-After`.\n\n## Errors\nErrors use one shape with a stable `code`:\n\n    {\"error\": {\"code\": \"validation_error\", \"message\": \"...\", \"fields\": [...], \"request_id\": \"...\"}}\n\n## Idempotency\nSend an `Idempotency-Key` header on `POST /calls`, `POST /campaigns` and `POST /campaigns/{id}/contacts`.\nRetrying with the same key and body within 24 hours returns the original result and never places a\nsecond call.\n\n## Pagination\nLists return `{\"data\": [...], \"next_cursor\": \"...\"}`, newest first. Pass `cursor` to get the next page.\n\n## Webhooks\nAdd an endpoint under **Integrations → Webhooks** to receive `call.started`, `call.ended`,\n`call.failed` and `call.analyzed` (sent after `call.ended`, with the transcript and summary). Each\ndelivery is signed:\n\n    Voxlyn-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>\n\nVerify it with your webhook secret, reject timestamps older than 5 minutes, and ignore repeated event\nids (`Voxlyn-Event-Id`). Failed deliveries are retried for up to 24 hours.","version":"1.0.0"},"servers":[{"url":"http://localhost:8000","description":"Production"}],"paths":{"/public/v1/calls":{"post":{"tags":["Calls"],"summary":"Create a call","description":"Phone `to` with an agent, now or at `scheduled_at`. Returns at once with the call `id`; follow it\nwith `GET /calls/{call_id}` or a `call.ended` webhook. Billed like every call: included minutes,\nthen overage up to your cap, with the agent's billing weight. There is no per-request fee.","operationId":"public_create_call_public_v1_calls_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again.","title":"Idempotency-Key"},"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCallRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"No minutes left (`no_minutes`), overage cap reached (`overage_cap_reached`), overage suspended (`overage_suspended`), key cap reached (`api_key_cap_reached`) or no API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit (`rate_limited`) or concurrent API call limit (`api_concurrency_limit`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Invalid input (`validation_error`) with per-field errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Idempotency-Key reused with a different body (`idempotency_mismatch`) or still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"get":{"tags":["Calls"],"summary":"List calls","description":"Newest first. Every call of the workspace, whichever way it was started.","operationId":"public_list_calls_public_v1_calls_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["queued","dialing","in_progress","completed","failed","cancelled"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Agent Id"}},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"enum":["dashboard","inbound","web","campaign","schedule","api"],"type":"string"},{"type":"null"}],"title":"Source"}},{"name":"api_key_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Only calls placed with this key.","title":"Api Key Id"},"description":"Only calls placed with this key."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After"}},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1–100).","default":20,"title":"Limit"},"description":"Page size (1–100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page.","title":"Cursor"},"description":"`next_cursor` from the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallList"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/v1/calls/{call_id}":{"get":{"tags":["Calls"],"summary":"Get a call","description":"Status, timing, billable minutes and, once spoken, the transcript.","operationId":"public_get_call_public_v1_calls__call_id__get","security":[{"bearerAuth":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Calls"],"summary":"End or cancel a call","description":"Cancels a queued or dialling call (it is never rung), or hangs up a live one. Only connected\ntime is billed.","operationId":"public_end_call_public_v1_calls__call_id__delete","security":[{"bearerAuth":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The call already ended (`call_already_ended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/v1/calls/{call_id}/recording":{"get":{"tags":["Calls"],"summary":"Download the recording","description":"The call's audio, streamed through Voxlyn (404 when the call has no recording).","operationId":"public_call_recording_public_v1_calls__call_id__recording_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"MP3 audio.","content":{"audio/mpeg":{}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/v1/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Includes `billing_weight`: how many billable minutes one connected minute counts.","operationId":"public_list_agents_public_v1_agents_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1–100).","default":20,"title":"Limit"},"description":"Page size (1–100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page.","title":"Cursor"},"description":"`next_cursor` from the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/v1/phone-numbers":{"get":{"tags":["Phone numbers"],"summary":"List phone numbers","description":"Your numbers and the agent each one is assigned to. Use one as `from` when creating a call.","operationId":"public_list_numbers_public_v1_phone_numbers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberList"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearerAuth":[]}]}},"/public/v1/campaigns":{"post":{"tags":["Campaigns"],"summary":"Create a campaign","description":"Calls each contact with the agent, paced, starting now or at `scheduled_at`. Each call is billed\nlike any other API call of this key.","operationId":"public_create_campaign_public_v1_campaigns_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again.","title":"Idempotency-Key"},"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include campaigns (`plan_feature_missing`) or no minutes left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Invalid input (`validation_error`) with per-field errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Not allowed in the campaign's current status, or an Idempotency-Key conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"get":{"tags":["Campaigns"],"summary":"List campaigns","operationId":"public_list_campaigns_public_v1_campaigns_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["queued","running","paused","completed","failed","cancelled"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size (1–100).","default":20,"title":"Limit"},"description":"Page size (1–100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page.","title":"Cursor"},"description":"`next_cursor` from the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/v1/campaigns/{campaign_id}":{"get":{"tags":["Campaigns"],"summary":"Get a campaign","description":"The campaign with live contact counts in `stats`.","operationId":"public_get_campaign_public_v1_campaigns__campaign_id__get","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Campaigns"],"summary":"Update a campaign","description":"Rename it, pause it (contacts not yet dialled wait), resume a paused campaign, or cancel it\n(`status: cancelled` skips every contact not yet dialled and hangs up calls in progress).","operationId":"public_update_campaign_public_v1_campaigns__campaign_id__patch","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCampaignRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include campaigns (`plan_feature_missing`) or no minutes left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Invalid input (`validation_error`) with per-field errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Not allowed in the campaign's current status, or an Idempotency-Key conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/public/v1/campaigns/{campaign_id}/contacts":{"post":{"tags":["Campaigns"],"summary":"Add contacts (JSON)","description":"Up to 1,000 contacts. Invalid rows are reported in `rejected` (by index); the rest are added.","operationId":"public_add_contacts_public_v1_campaigns__campaign_id__contacts_post","security":[{"bearerAuth":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again.","title":"Idempotency-Key"},"description":"Retry-safe create: the same key + same body within 24 h returns the original result without creating anything again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsResult"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include campaigns (`plan_feature_missing`) or no minutes left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (also for another workspace's ids).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"422":{"description":"Invalid input (`validation_error`) with per-field errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Not allowed in the campaign's current status, or an Idempotency-Key conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/public/v1/usage":{"get":{"tags":["Usage"],"summary":"Get key, plan and usage","description":"The workspace and key behind the request, the plan and its API limits, and this billing period's\nincluded / used / remaining minutes, overage, and per-key requests, calls and billable minutes. A cheap\nway to check a key works. Requests are counted with up to a minute's delay.","operationId":"public_usage_public_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing, invalid, revoked or expired API key (`unauthenticated`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Plan doesn't include API access (`plan_feature_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); see `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"bearerAuth":[]}]}}},"webhooks":{"call.started":{"post":{"summary":"A call was answered","description":"Sent when a call connects.","operationId":"call_startedcall_started_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"call.ended":{"post":{"summary":"A call ended","description":"Sent once when a call that connected has ended, with its billable minutes.","operationId":"call_endedcall_ended_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"call.failed":{"post":{"summary":"A call failed or was cancelled","description":"Sent when a call couldn't connect (no answer, busy, refused for minutes) or was cancelled.","operationId":"call_failedcall_failed_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"call.analyzed":{"post":{"summary":"A call's transcript and summary are ready","description":"Sent once per call, usually within a minute of `call.ended`, after the transcript has been\nsummarised. `summary` is null when there was nothing to summarise or the analysis failed.","operationId":"call_analyzedcall_analyzed_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallAnalyzedEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddContactsRequest":{"properties":{"contacts":{"items":{"$ref":"#/components/schemas/RawContact"},"type":"array","maxItems":1000,"minItems":1,"title":"Contacts"}},"type":"object","required":["contacts"],"title":"AddContactsRequest"},"AddContactsResult":{"properties":{"added":{"type":"integer","title":"Added"},"rejected":{"items":{"$ref":"#/components/schemas/RejectedContact"},"type":"array","title":"Rejected"}},"type":"object","required":["added","rejected"],"title":"AddContactsResult"},"Agent":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"status":{"type":"string","title":"Status","description":"`active` or `draft`."},"is_active":{"type":"boolean","title":"Is Active"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"voice_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Id"},"phone_numbers":{"items":{"type":"string"},"type":"array","title":"Phone Numbers","default":[]},"billing_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billing Weight","description":"Billable minutes one connected minute counts (1.5 for premium models/voices)."}},"type":"object","required":["id","name","status","is_active"],"title":"Agent"},"AgentList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"AgentList"},"AnalyzedCall":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["queued","dialing","in_progress","completed","failed","cancelled"],"title":"Status","description":"`queued` (scheduled), `dialing`, `in_progress`, `completed`, `failed` or `cancelled`."},"direction":{"type":"string","title":"Direction","description":"`outbound`, `inbound` or `web`."},"source":{"anyOf":[{"type":"string","enum":["dashboard","inbound","web","campaign","schedule","api"]},{"type":"string"}],"title":"Source","description":"Where the call was started.","default":"dashboard"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the call was answered."},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"connected_seconds":{"type":"integer","title":"Connected Seconds","description":"Connected time once the call has ended.","default":0},"billable_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billable Minutes","description":"Connected minutes × the agent's billing weight (1.5 for premium models/voices)."},"billing_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billing Weight"},"end_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Reason"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"transcript":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptTurn"},"type":"array"},{"type":"null"}],"title":"Transcript","description":"The conversation in order. Only on `GET /calls/{call_id}`; null in lists."},"summary":{"anyOf":[{"$ref":"#/components/schemas/CallSummary"},{"type":"null"}],"description":"Null when the call had no transcript or the analysis failed."}},"type":"object","required":["id","status","direction"],"title":"AnalyzedCall"},"Call":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["queued","dialing","in_progress","completed","failed","cancelled"],"title":"Status","description":"`queued` (scheduled), `dialing`, `in_progress`, `completed`, `failed` or `cancelled`."},"direction":{"type":"string","title":"Direction","description":"`outbound`, `inbound` or `web`."},"source":{"anyOf":[{"type":"string","enum":["dashboard","inbound","web","campaign","schedule","api"]},{"type":"string"}],"title":"Source","description":"Where the call was started.","default":"dashboard"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When the call was answered."},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"},"connected_seconds":{"type":"integer","title":"Connected Seconds","description":"Connected time once the call has ended.","default":0},"billable_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billable Minutes","description":"Connected minutes × the agent's billing weight (1.5 for premium models/voices)."},"billing_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Billing Weight"},"end_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Reason"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"transcript":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptTurn"},"type":"array"},{"type":"null"}],"title":"Transcript","description":"The conversation in order. Only on `GET /calls/{call_id}`; null in lists."}},"type":"object","required":["id","status","direction"],"title":"Call"},"CallAnalyzedEvent":{"properties":{"id":{"type":"string","title":"Id","description":"Unique event id (also the `Voxlyn-Event-Id` header). Dedupe on it."},"type":{"type":"string","const":"call.analyzed","title":"Type"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"data":{"$ref":"#/components/schemas/AnalyzedCall","description":"The call with its full `transcript` and `summary`."}},"type":"object","required":["id","type","created_at","data"],"title":"CallAnalyzedEvent"},"CallList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Call"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` to get the next page; null on the last page."}},"type":"object","required":["data"],"title":"CallList"},"CallSummary":{"properties":{"summary":{"type":"string","title":"Summary","description":"Two or three sentences about the call."},"sentiment":{"type":"string","title":"Sentiment","description":"`positive`, `neutral` or `negative`."},"action_items":{"items":{"type":"string"},"type":"array","title":"Action Items","default":[]}},"type":"object","required":["summary","sentiment"],"title":"CallSummary"},"Campaign":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"status":{"anyOf":[{"type":"string","enum":["queued","running","paused","completed","failed","cancelled"]},{"type":"string"}],"title":"Status"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"total_contacts":{"type":"integer","title":"Total Contacts","default":0},"called":{"type":"integer","title":"Called","default":0},"completed":{"type":"integer","title":"Completed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"pending":{"type":"integer","title":"Pending","default":0},"stats":{"anyOf":[{"$ref":"#/components/schemas/CampaignStats"},{"type":"null"}],"description":"Live contact counts. Only on `GET /campaigns/{campaign_id}`; null in lists."}},"type":"object","required":["id","name","status"],"title":"Campaign"},"CampaignList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Campaign"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"CampaignList"},"CampaignStats":{"properties":{"total":{"type":"integer","title":"Total"},"pending":{"type":"integer","title":"Pending"},"calling":{"type":"integer","title":"Calling"},"completed":{"type":"integer","title":"Completed"},"failed":{"type":"integer","title":"Failed"},"skipped":{"type":"integer","title":"Skipped"}},"type":"object","required":["total","pending","calling","completed","failed","skipped"],"title":"CampaignStats"},"ContactIn":{"properties":{"phone_number":{"type":"string","title":"Phone Number"},"context":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Context"}},"type":"object","required":["phone_number"],"title":"ContactIn"},"CreateCallRequest":{"properties":{"agent_id":{"type":"string","minLength":1,"title":"Agent Id","description":"The agent that runs the call (GET /agents)."},"to":{"type":"string","title":"To","description":"The number to call, E.164."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From","description":"One of your active numbers (GET /phone-numbers). Defaults to your first active number."},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"Place the call later (UTC offset required, at most 30 days ahead). Omit to call now."},"context":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Context","description":"Extra instructions or facts for the agent for this call only."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own data (≤ 4 KB JSON), returned on reads and in webhooks. Never shown to the caller."}},"additionalProperties":false,"type":"object","required":["agent_id","to"],"title":"CreateCallRequest","examples":[{"agent_id":"8b1e6f0a-3c2d-4e5f-9a8b-7c6d5e4f3a2b","context":"Patient Jane Doe, cleaning appointment tomorrow at 10:30. Confirm or reschedule.","metadata":{"appointment_id":"A-1042"},"to":"+12125550100"}]},"CreateCampaignRequest":{"properties":{"agent_id":{"type":"string","minLength":1,"title":"Agent Id"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","default":"Untitled Campaign"},"scheduled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Scheduled At","description":"Start later (UTC offset required). Omit to start now."},"contacts":{"items":{"$ref":"#/components/schemas/ContactIn"},"type":"array","maxItems":1000,"minItems":1,"title":"Contacts"}},"additionalProperties":false,"type":"object","required":["agent_id","contacts"],"title":"CreateCampaignRequest","examples":[{"agent_id":"8b1e6f0a-3c2d-4e5f-9a8b-7c6d5e4f3a2b","contacts":[{"context":"Lead from the open house","phone_number":"+12125550100"}],"name":"October follow-ups"}]},"ErrorBody":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["error"],"title":"ErrorBody","examples":[{"error":{"code":"validation_error","fields":[{"field":"to","message":"must be an E.164 phone number, e.g. +12125550100"}],"message":"to: must be an E.164 phone number, e.g. +12125550100","request_id":"4f0c2b9e5d0a4c1f8f7e2a1b3c4d5e6f"}}]},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine-readable code, e.g. `validation_error`, `api_key_cap_reached`."},"message":{"type":"string","title":"Message","description":"Human-readable explanation."},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorField"},"type":"array"},{"type":"null"}],"title":"Fields"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Quote this when contacting support."}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"ErrorField":{"properties":{"field":{"type":"string","title":"Field","description":"The request field, e.g. `to` or `contacts.2.phone_number`."},"message":{"type":"string","title":"Message"}},"type":"object","required":["field","message"],"title":"ErrorField"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix","description":"The first characters of the key, safe to display."},"scopes":{"items":{"type":"string","enum":["read","calls","campaigns"]},"type":"array","title":"Scopes"},"monthly_minute_cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Minute Cap","description":"Billable minutes this key may use per billing period; null = no key cap (the workspace cap applies)."}},"type":"object","required":["id","name","prefix","scopes"],"title":"KeyInfo"},"KeyUsage":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix"},"requests":{"type":"integer","title":"Requests"},"calls_created":{"type":"integer","title":"Calls Created"},"billable_minutes":{"type":"number","title":"Billable Minutes"},"monthly_minute_cap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Minute Cap"}},"type":"object","required":["id","name","prefix","requests","calls_created","billable_minutes"],"title":"KeyUsage"},"Limits":{"properties":{"requests_per_minute":{"type":"integer","title":"Requests Per Minute","description":"Per key."},"max_concurrent_calls":{"type":"integer","title":"Max Concurrent Calls","description":"Calls placed through the API that may be live at once, per workspace."},"campaigns":{"type":"boolean","title":"Campaigns","description":"Whether the plan includes outbound campaigns."}},"type":"object","required":["requests_per_minute","max_concurrent_calls","campaigns"],"title":"Limits"},"MinutesUsage":{"properties":{"included":{"type":"number","title":"Included"},"used":{"type":"number","title":"Used"},"remaining":{"type":"number","title":"Remaining"}},"type":"object","required":["included","used","remaining"],"title":"MinutesUsage"},"OverageUsage":{"properties":{"status":{"type":"string","title":"Status","description":"`active`, `off`, `suspended`, `not_yet` or `unavailable` (Trial)."},"minutes":{"type":"number","title":"Minutes"},"cost_cents":{"type":"number","title":"Cost Cents"},"cap_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cap Cents"}},"type":"object","required":["status","minutes","cost_cents"],"title":"OverageUsage"},"PhoneNumber":{"properties":{"id":{"type":"string","title":"Id"},"number":{"type":"string","title":"Number"},"status":{"type":"string","title":"Status"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},"type":"object","required":["id","number","status"],"title":"PhoneNumber"},"PhoneNumberList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PhoneNumber"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"PhoneNumberList"},"RawContact":{"properties":{"phone_number":{"type":"string","title":"Phone Number","default":""},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"}},"type":"object","title":"RawContact","description":"Validated per row, so one bad number doesn't reject the whole batch."},"RejectedContact":{"properties":{"index":{"type":"integer","title":"Index","description":"0-based position in `contacts`."},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["index","reason"],"title":"RejectedContact"},"TranscriptTurn":{"properties":{"role":{"type":"string","title":"Role","description":"`agent` or `user` (the caller)."},"text":{"type":"string","title":"Text"},"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At"}},"type":"object","required":["role","text"],"title":"TranscriptTurn"},"UpdateCampaignRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name"},"status":{"anyOf":[{"type":"string","enum":["paused","running","cancelled"]},{"type":"null"}],"title":"Status","description":"`paused` stops dialling new contacts; `running` resumes a paused campaign; `cancelled` skips every contact not yet dialled and hangs up calls in progress (final)."}},"additionalProperties":false,"type":"object","title":"UpdateCampaignRequest"},"UsagePeriod":{"properties":{"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"},"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},"type":"object","title":"UsagePeriod"},"UsageResponse":{"properties":{"workspace":{"$ref":"#/components/schemas/Workspace"},"key":{"$ref":"#/components/schemas/KeyInfo","description":"The key that made this request."},"plan":{"type":"string","title":"Plan"},"limits":{"$ref":"#/components/schemas/Limits"},"period":{"$ref":"#/components/schemas/UsagePeriod"},"minutes":{"$ref":"#/components/schemas/MinutesUsage"},"overage":{"$ref":"#/components/schemas/OverageUsage"},"keys":{"items":{"$ref":"#/components/schemas/KeyUsage"},"type":"array","title":"Keys"}},"type":"object","required":["workspace","key","plan","limits","period","minutes","overage","keys"],"title":"UsageResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookEvent":{"properties":{"id":{"type":"string","title":"Id","description":"Unique event id (also the `Voxlyn-Event-Id` header). Dedupe on it."},"type":{"type":"string","enum":["call.started","call.ended","call.failed"],"title":"Type"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"data":{"$ref":"#/components/schemas/Call"}},"type":"object","required":["id","type","created_at","data"],"title":"WebhookEvent"},"Workspace":{"properties":{"id":{"type":"string","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","required":["id"],"title":"Workspace"}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Your secret API key (`vxk_live_…`), created in the dashboard under Integrations → API keys.","scheme":"bearer"}}},"tags":[{"name":"Calls","description":"Place, follow, end and read calls."},{"name":"Agents","description":"Your voice agents (read-only)."},{"name":"Phone numbers","description":"Your numbers (read-only)."},{"name":"Campaigns","description":"Call many contacts with one agent."},{"name":"Usage","description":"The key, plan and limits behind a request, and this period's minutes."}],"security":[{"bearerAuth":[]}]}