{"openapi":"3.1.0","info":{"title":"VoiceDoc agent access","version":"1"},"servers":[{"url":"https://api.voicedoc.ai"}],"paths":{"/v1/agent/actions/onboarding_complete":{"post":{"operationId":"onboarding_complete","description":"Activate the paid shared interpreter and the first receptionist number and agent","security":[{"agentBearer":[]}],"x-required-scope":"onboarding:manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/org_get":{"post":{"operationId":"org_get","description":"Read this organization's public profile","security":[{"agentBearer":[]}],"x-required-scope":"org:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/org_update":{"post":{"operationId":"org_update","description":"Change allowed business profile fields","security":[{"agentBearer":[]}],"x-required-scope":"org:settings:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":1024},"timezone":{"type":"string","minLength":1,"maxLength":1024}},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/agents_list":{"post":{"operationId":"agents_list","description":"List agents allowed by this grant","security":[{"agentBearer":[]}],"x-required-scope":"agents:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/agents_get":{"post":{"operationId":"agents_get","description":"Read an allowed agent's safe configuration","security":[{"agentBearer":[]}],"x-required-scope":"agents:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"agentId":{"type":"string","minLength":1,"maxLength":1024}},"required":["agentId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/agents_draft":{"post":{"operationId":"agents_draft","description":"Save a server-side configuration draft","security":[{"agentBearer":[]}],"x-required-scope":"agents:configure","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"agentId":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":1024},"systemPrompt":{"type":"string","minLength":1,"maxLength":32768},"greetingMessage":{"type":"string","minLength":1,"maxLength":1024},"timezone":{"type":"string","minLength":1,"maxLength":1024},"voiceName":{"type":"string","minLength":1,"maxLength":1024},"lastSeenVersionId":{"type":"string","minLength":1,"maxLength":1024}},"required":["agentId","lastSeenVersionId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/agents_publish":{"post":{"operationId":"agents_publish","description":"Test and publish the exact server-side draft","security":[{"agentBearer":[]}],"x-required-scope":"agents:publish","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"agentId":{"type":"string","minLength":1,"maxLength":1024},"draftId":{"type":"string","minLength":1,"maxLength":1024}},"required":["agentId","draftId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/calls_list":{"post":{"operationId":"calls_list","description":"Read authorized call metadata, never the host's entire call list","security":[{"agentBearer":[]}],"x-required-scope":"calls:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"agentId":{"type":"string","minLength":1,"maxLength":1024},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string","minLength":1,"maxLength":1024}},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/calls_transcript":{"post":{"operationId":"calls_transcript","description":"Read an authorized unprotected call transcript","security":[{"agentBearer":[]}],"x-required-scope":"calls:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversationId":{"type":"string","minLength":1,"maxLength":1024}},"required":["conversationId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/usage_get":{"post":{"operationId":"usage_get","description":"Read this organization's usage and balance","security":[{"agentBearer":[]}],"x-required-scope":"usage:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/staff_phones_list":{"post":{"operationId":"staff_phones_list","description":"List this organization's interpreter caller registrations","security":[{"agentBearer":[]}],"x-required-scope":"interpreter:phones:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/staff_phones_add":{"post":{"operationId":"staff_phones_add","description":"Register a caller without overriding another organization's ownership","security":[{"agentBearer":[]}],"x-required-scope":"interpreter:phones:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"phone":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":1024}},"required":["phone","name"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/staff_phones_rename":{"post":{"operationId":"staff_phones_rename","description":"Rename this organization's caller registration","security":[{"agentBearer":[]}],"x-required-scope":"interpreter:phones:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"callerId":{"type":"string","minLength":1,"maxLength":1024},"name":{"type":"string","minLength":1,"maxLength":1024}},"required":["callerId","name"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/staff_phones_remove":{"post":{"operationId":"staff_phones_remove","description":"Remove this organization's caller registration","security":[{"agentBearer":[]}],"x-required-scope":"interpreter:phones:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"callerId":{"type":"string","minLength":1,"maxLength":1024}},"required":["callerId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/staff_phones_allowance":{"post":{"operationId":"staff_phones_allowance","description":"Set a caller's allocation, never grant free credit","security":[{"agentBearer":[]}],"x-required-scope":"interpreter:allowances:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"callerId":{"type":"string","minLength":1,"maxLength":1024},"minutes":{"type":"integer","minimum":0},"refresh":{"type":"string","minLength":1,"maxLength":1024}},"required":["callerId","minutes","refresh"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/members_list":{"post":{"operationId":"members_list","description":"Read this organization's roster","security":[{"agentBearer":[]}],"x-required-scope":"members:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/members_invite":{"post":{"operationId":"members_invite","description":"Invite a staff member within the grant's delegation ceiling","security":[{"agentBearer":[]}],"x-required-scope":"members:invite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","minLength":1,"maxLength":1024},"agentIds":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","format":"uuid"}}},"required":["email","agentIds"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/members_assign":{"post":{"operationId":"members_assign","description":"Assign staff only within the grant's existing resource permissions","security":[{"agentBearer":[]}],"x-required-scope":"members:assign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"membershipId":{"type":"string","minLength":1,"maxLength":1024},"agentIds":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","format":"uuid"}}},"required":["membershipId","agentIds"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/members_deactivate":{"post":{"operationId":"members_deactivate","description":"Deactivate staff, never an owner or manager","security":[{"agentBearer":[]}],"x-required-scope":"members:deactivate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"membershipId":{"type":"string","minLength":1,"maxLength":1024}},"required":["membershipId"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/billing_get":{"post":{"operationId":"billing_get","description":"Read this organization's billing summary without payment secrets","security":[{"agentBearer":[]}],"x-required-scope":"billing:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/funding_add":{"post":{"operationId":"funding_add","description":"Add funds within the owner-approved per-charge and monthly limits","security":[{"agentBearer":[]}],"x-required-scope":"billing:fund","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"amountCents":{"type":"integer","minimum":0},"sharedPaymentToken":{"type":"string","minLength":1,"maxLength":4096},"idempotencyKey":{"type":"string","minLength":1,"maxLength":1024}},"required":["amountCents","idempotencyKey"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/resources_request":{"post":{"operationId":"resources_request","description":"Request dedicated interpreter access or additional resources","security":[{"agentBearer":[]}],"x-required-scope":"resources:request","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"product":{"type":"string","minLength":1,"maxLength":1024},"reason":{"type":"string","minLength":1,"maxLength":1024},"estimatedMonthlyMinutes":{"type":"integer","minimum":0}},"required":["product","reason"]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/actions/resources_requests":{"post":{"operationId":"resources_requests","description":"Read this organization's expansion requests","security":[{"agentBearer":[]}],"x-required-scope":"resources:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Operation completed"},"403":{"description":"Permission denied"},"429":{"description":"Quota exceeded"}}}},"/v1/agent/onboarding":{"post":{"operationId":"start_onboarding","description":"Create an expiring draft; email identity and explicit consent are required before credentials or service. Store the returned setup token securely. No organization, model, or telephony authority is granted here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","company","orgType","services","codeChallenge"],"properties":{"email":{"type":"string","format":"email"},"company":{"type":"string","minLength":2,"maxLength":60},"orgType":{"enum":["medical","non_medical"]},"services":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"enum":["interpreter","receptionist"]}},"initialPrompt":{"type":"string","maxLength":32768,"description":"Required for receptionist"},"greeting":{"type":"string","maxLength":1024},"areaCode":{"type":"string","pattern":"^[2-9][0-9]{2}$"},"clientId":{"type":"string","default":"voicedoc-agent-api"},"resource":{"enum":["https://api.voicedoc.ai/v1/agent","https://api.voicedoc.ai/mcp"],"default":"https://api.voicedoc.ai/v1/agent"},"codeChallenge":{"type":"string","minLength":43,"maxLength":43,"description":"base64url SHA-256 of a fresh 43-128 character PKCE verifier; keep the verifier in client credential storage"}}}}}},"responses":{"200":{"description":"Draft-bound setup token and status URL; email recipient reviews the request"},"429":{"description":"Signup quota exceeded"}}}},"/v1/agent/onboarding/{id}":{"get":{"operationId":"onboarding_status","description":"Authorization: Bearer vd_setup_…; a draft token can only poll its own state. Exchange the returned single-use code at /agent-oauth/token with grant_type=authorization_code, client_id, original code_verifier, resource and redirect_uri=https://voicedoc.ai/connect/setup.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status and one-time PKCE-bound code after consent"},"401":{"description":"Invalid draft credential"}}}}},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer"}}}}