{"openapi":"3.0.3","info":{"title":"VoiceOrbit API","version":"1.0.1","description":"Trigger AI voice calls, manage campaigns, agents and contacts."},"servers":[{"url":"https://mail.voiceorbit.p.nextaweb.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from Settings → API keys (vk_live_…)"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"To is required."}}}}}}},"paths":{"/calls":{"post":{"tags":["Calls"],"summary":"Start an outbound AI call","description":"Supports the Idempotency-Key header. Variables fill {{placeholders}} in the agent prompt and first message.\n\nRequired scope: `calls:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"agent_id":12,"to":"+919876543210","variables":{"name":"Priya","amount":"2500"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120}}]},"get":{"tags":["Calls"],"summary":"List calls","description":"Filters: status, direction, agent_id, campaign_id, created_after (ISO date). Cursor pagination: limit (max 100), cursor.\n\nRequired scope: `calls:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/calls/{id}":{"get":{"tags":["Calls"],"summary":"Get a call with transcript and AI analysis","description":"Required scope: `calls:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/calls/{id}/hangup":{"post":{"tags":["Calls"],"summary":"End a live call","description":"Required scope: `calls:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/campaigns":{"post":{"tags":["Campaigns"],"summary":"Create a campaign (optionally with contacts)","description":"Supports Idempotency-Key. Without list_id a new contact list is created for the campaign.\n\nRequired scope: `campaigns:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"October renewals","agent_id":12,"timezone":"Asia/Kolkata","window_start":"10:00","window_end":"19:00","concurrency":3,"max_attempts":2,"contacts":[{"phone":"+919876543210","name":"Priya","variables":{"amount":"2500"}}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120}}]},"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Filter: status.\n\nRequired scope: `campaigns:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get a campaign with live progress","description":"Required scope: `campaigns:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Campaigns"],"summary":"Update name, window, concurrency or retries","description":"Required scope: `campaigns:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"concurrency":5}}}}},"delete":{"tags":["Campaigns"],"summary":"Delete a campaign","description":"Required scope: `campaigns:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/campaigns/{id}/start":{"post":{"tags":["Campaigns"],"summary":"Start (or resume) a campaign","description":"Also /pause and /resume.\n\nRequired scope: `campaigns:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/campaigns/{id}/contacts":{"post":{"tags":["Campaigns"],"summary":"Add contacts to a campaign","description":"Up to 1000 per request. Running campaigns dial them automatically.\n\nRequired scope: `campaigns:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"contacts":[{"phone":"+919812345678","name":"Arjun"}]}}}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Required scope: `agents:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Agents"],"summary":"Create an agent","description":"Required scope: `agents:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Riya — Sales","language":"en-IN","system_prompt":"You are Riya…","first_message":"Hi {{name}}!"}}}}}},"/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get an agent","description":"Required scope: `agents:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Agents"],"summary":"Update an agent","description":"Required scope: `agents:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"first_message":"Hello {{name}}, this is Riya."}}}}},"delete":{"tags":["Agents"],"summary":"Delete an agent","description":"Required scope: `agents:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Filters: phone, lead_status, tag.\n\nRequired scope: `contacts:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Contacts"],"summary":"Create or update a contact (dedupes by phone)","description":"Required scope: `contacts:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"phone":"+919876543210","name":"Priya","tags":"website,hot","custom_fields":{"city":"Kolkata"},"list_id":3}}}}}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Get a contact","description":"Required scope: `contacts:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Contacts"],"summary":"Update a contact","description":"Required scope: `contacts:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"example":{"lead_status":"qualified"}}}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact","description":"Required scope: `contacts:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/me":{"get":{"tags":["Account"],"summary":"Workspace, plan and key info","description":"","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/credits/balance":{"get":{"tags":["Account"],"summary":"Credit balance","description":"Required scope: `credits:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/credits/usage":{"get":{"tags":["Account"],"summary":"Credit ledger","description":"Required scope: `credits:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/analytics/calls":{"get":{"tags":["Account"],"summary":"Call analytics","description":"Query: days (1–365), direction (inbound|outbound|campaign).\n\nRequired scope: `analytics:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/numbers":{"get":{"tags":["Account"],"summary":"Phone numbers available to you","description":"Required scope: `numbers:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Required scope: `webhooks:read`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook (returns its signing secret once)","description":"Events: call.started, call.answered, call.completed, call.failed, call.analysis_ready, campaign.started, campaign.completed, lead.qualified, credits.low, task.triggered or \"*\".\n\nRequired scope: `webhooks:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"example":{"url":"https://example.com/hooks/voice","events":["call.completed","lead.qualified"]}}}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test event","description":"Required scope: `webhooks:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Required scope: `webhooks:write`.","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}}}}