{"openapi":"3.1.0","info":{"title":"Vexium Voice Customer API","version":"1.0.0","description":"Customer machine API. Authenticate with Authorization: Bearer vx_live_REPLACE_ME. Every credential is bound to one tenant and its granted scopes. Lists use the fixed ListEnvelope and errors use the fixed ErrorEnvelope."},"servers":[{"url":"https://api.vexiumvoice.app/v1","description":"Production"}],"externalDocs":{"description":"Vexium Voice API documentation","url":"https://docs.vexiumvoice.app"},"security":[{"BearerAuth":[]}],"tags":[{"name":"Authentication"},{"name":"Agents"},{"name":"Calls"},{"name":"Captures"},{"name":"Usage"},{"name":"Connections"},{"name":"Knowledge"}],"paths":{"/whoami":{"get":{"summary":"Inspect the current credential","tags":["Authentication"],"description":"Returns tenant identity, mode, key prefix, and granted scopes; never returns the secret.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["authenticated_as","livemode","tenant","scopes"],"properties":{"authenticated_as":{"type":"string"},"livemode":{"type":"boolean"},"tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"}}},"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/scopes":{"get":{"summary":"List available scopes","tags":["Authentication"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["scopes"],"properties":{"scopes":{"type":"array","items":{"type":"object"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/usage":{"get":{"summary":"Get usage","tags":["Usage"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["usage:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["livemode","current_period_seconds","history"],"properties":{"livemode":{"type":"boolean"},"current_period_seconds":{"type":"integer"},"history":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"seconds":{"type":"integer"},"calls":{"type":"integer"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/agents":{"get":{"summary":"List agents","tags":["Agents"],"description":"Returns customer-safe business configuration without provider credentials.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["agents:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["agents"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/agents/{slug}":{"patch":{"summary":"Update an agent","tags":["Agents"],"description":"Only the fields defined by AgentPatch are editable. Use voice IDs from GET /voices. ATOMIC REPLACEMENT WARNING: hours, menu, products, services, and listings are complete datasets. Supplying any one of these fields replaces that field wholesale; omitted entries are deleted rather than merged. Read the current agent, modify the complete field, then send the replacement.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["agents:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"parameters":[{"name":"slug","in":"path","required":true,"description":"Agent slug.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"ATOMIC REPLACEMENT WARNING: hours, menu, products, services, and listings are complete datasets. Supplying any one of these fields replaces that field wholesale; omitted entries are deleted rather than merged. Read the current agent, modify the complete field, then send the replacement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPatchRequest"}}}}}},"/voices":{"get":{"summary":"List selectable voices","tags":["Agents"],"description":"Returns opaque Vexium IDs, not provider identifiers.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["agents:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["voices"],"properties":{"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/calls":{"get":{"summary":"List calls","tags":["Calls"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["calls:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (default 25, maximum 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"starting_after","in":"query","required":false,"description":"ID from next_starting_after on the previous page.","schema":{"type":"string"}},{"name":"outcome","in":"query","required":false,"description":"Filter by call outcome.","schema":{"type":"string","enum":["booking","info","handoff","abandoned","error","over_limit"]}},{"name":"channel","in":"query","required":false,"description":"Filter by channel.","schema":{"type":"string","enum":["web","phone"]}}]}},"/calls/{call_id}":{"get":{"summary":"Get a call with transcript","tags":["Calls"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["calls:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["call"],"properties":{"call":{"$ref":"#/components/schemas/CallDetail"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"call_id","in":"path","required":true,"description":"Call UUID.","schema":{"type":"string"}}]}},"/analytics":{"get":{"summary":"Get call analytics","tags":["Calls"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["calls:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["days","timezone","per_day","by_hour","totals"],"properties":{"days":{"type":"integer"},"timezone":{"type":"string"},"per_day":{"type":"array","items":{"type":"object"}},"by_hour":{"type":"array","items":{"type":"object"}},"totals":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/captures":{"get":{"summary":"List captures","tags":["Captures"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["captures:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Capture"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (default 25, maximum 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"starting_after","in":"query","required":false,"description":"ID from next_starting_after on the previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by capture status.","schema":{"type":"string","enum":["pending_confirm","confirmed","cancelled","no_show"]}},{"name":"kind","in":"query","required":false,"description":"Filter by capture type.","schema":{"type":"string"}}]}},"/captures/{capture_id}":{"get":{"summary":"Get a capture","tags":["Captures"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["captures:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["capture"],"properties":{"capture":{"$ref":"#/components/schemas/Capture"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"capture_id","in":"path","required":true,"description":"Capture UUID.","schema":{"type":"string"}}]},"patch":{"summary":"Update capture status","tags":["Captures"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["captures:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["capture"],"properties":{"capture":{"$ref":"#/components/schemas/Capture"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"parameters":[{"name":"capture_id","in":"path","required":true,"description":"Capture UUID.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The only editable capture field is status.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["pending_confirm","confirmed","cancelled","no_show"]}}}}}}}},"/connectors":{"get":{"summary":"List connector types","tags":["Connections"],"description":"Includes event vocabulary, signature contract, delivery requirements, and limits.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/connections":{"get":{"summary":"List connections","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."},"limits":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"summary":"Create a connection","tags":["Connections"],"description":"The HMAC secret is returned only in this response. Store it securely.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"requestBody":{"required":true,"description":"Connection destination and subscribed events. livemode comes from the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionInput"}}}}}},"/connections/{connection_id}":{"get":{"summary":"Get a connection","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}]},"patch":{"summary":"Update a connection","tags":["Connections"],"description":"Use the enable and disable actions for lifecycle changes.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Update name, URL, or complete event subscription list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionPatch"}}}}},"delete":{"summary":"Delete a connection","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}]}},"/connections/{connection_id}/enable":{"post":{"summary":"Enable a connection","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}]}},"/connections/{connection_id}/disable":{"post":{"summary":"Disable a connection","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Optional customer-visible disable reason.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","maxLength":200}}}}}}}},"/connections/{connection_id}/test":{"post":{"summary":"Send a signed test delivery","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["ok","http_status","latency_ms"],"properties":{"ok":{"type":"boolean"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"latency_ms":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}]}},"/connections/{connection_id}/rotate-secret":{"post":{"summary":"Rotate a connection secret","tags":["Connections"],"description":"The new HMAC secret is returned only in this response.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["connection"],"properties":{"connection":{"$ref":"#/components/schemas/Connection"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Optional overlap period during which both old and new secrets sign deliveries.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"grace_seconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}}}}}}},"/connections/{connection_id}/deliveries":{"get":{"summary":"List connection deliveries","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."},"connection_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"connection_id","in":"path","required":true,"description":"Connection UUID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (default 25, maximum 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"starting_after","in":"query","required":false,"description":"ID from next_starting_after on the previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by delivery status.","schema":{"type":"string"}}]}},"/deliveries/{delivery_id}/retry":{"post":{"summary":"Retry a failed delivery","tags":["Connections"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["connections:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["ok","delivery"],"properties":{"ok":{"type":"boolean"},"delivery":{"$ref":"#/components/schemas/Delivery"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"delivery_id","in":"path","required":true,"description":"Delivery UUID.","schema":{"type":"string"}}]}},"/knowledge":{"get":{"summary":"Get knowledge summary","tags":["Knowledge"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["summary","limits","livemode"],"properties":{"summary":{"type":"object"},"limits":{"type":"object"},"livemode":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/knowledge/documents":{"get":{"summary":"List knowledge documents","tags":["Knowledge"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."},"limits":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by processing status.","schema":{"type":"string","enum":["pending","processing","ready","error","archived"]}},{"name":"agent_id","in":"query","required":false,"description":"Limit to one agent UUID.","schema":{"type":"string"}}]},"post":{"summary":"Upload a knowledge document","tags":["Knowledge"],"description":"Supply the filename through either X-Vexium-Filename or the filename query parameter; at least one is required. Returns pending immediately; poll the document detail until status is ready.","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:write"],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["document","deduped","limits"],"properties":{"document":{"$ref":"#/components/schemas/Document"},"deduped":{"type":"boolean"},"limits":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"502":{"$ref":"#/components/responses/BadGateway"}},"parameters":[{"name":"X-Vexium-Filename","in":"header","required":false,"description":"Optional filename including .pdf, .md, .csv, or .txt; required only when the filename query parameter is absent.","schema":{"type":"string"}},{"name":"title","in":"query","required":false,"description":"Optional display title.","schema":{"type":"string"}},{"name":"agent_id","in":"query","required":false,"description":"Optional agent UUID scope.","schema":{"type":"string"}},{"name":"filename","in":"query","required":false,"description":"Optional filename fallback; required only when X-Vexium-Filename is absent.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Raw document bytes, not multipart form data.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string","format":"binary"}},"text/markdown":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}},"/knowledge/documents/{document_id}":{"get":{"summary":"Get a knowledge document","tags":["Knowledge"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"$ref":"#/components/schemas/Document"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"document_id","in":"path","required":true,"description":"Knowledge document UUID.","schema":{"type":"string"}}]},"delete":{"summary":"Delete a knowledge document","tags":["Knowledge"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:write"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean"},"id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"parameters":[{"name":"document_id","in":"path","required":true,"description":"Knowledge document UUID.","schema":{"type":"string"}}]}},"/knowledge/test":{"post":{"summary":"Test a knowledge question","tags":["Knowledge"],"description":"","security":[{"BearerAuth":[]}],"x-vexium-required-scopes":["knowledge:read"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","required":["question","answered","answer","sources","fragments","match_pct","threshold_pct"],"properties":{"question":{"type":"string"},"livemode":{"type":"boolean"},"answered":{"type":"boolean"},"answer":{},"message_es":{"type":"string"},"message_en":{"type":"string"},"sources":{"type":"array","items":{}},"fragments":{"type":"array","items":{"type":"object"}},"match_pct":{"type":"number"},"threshold_pct":{"type":"number"},"confidence":{"type":"string"},"explanation":{"type":"string"},"elapsed_ms":{"type":"number"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}},"requestBody":{"required":true,"description":"Question to resolve with the same knowledge path used during a live call.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":300},"agent_id":{"type":"string","format":"uuid"}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Vexium API key","description":"Use Authorization: Bearer vx_live_REPLACE_ME. Scopes are listed in x-vexium-required-scopes."}},"schemas":{"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["type","code","message","param","request_id"],"properties":{"type":{"type":"string","examples":["invalid_request_error"]},"code":{"type":"string","examples":["not_found"]},"message":{"type":"string"},"param":{"anyOf":[{"type":"string"},{"type":"null"}]},"request_id":{"type":"string"}}}}},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_starting_after"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"}},"has_more":{"type":"boolean"},"next_starting_after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass this value as starting_after to fetch the next page."}}},"Hours":{"type":"object","description":"Weekly structured hours. Keys are weekday numbers as strings (0=Monday through 6=Sunday); each value is [opening_hour, closing_hour] using whole hours on a 24-hour clock. Omit a day to mark it closed. Example: {\"0\":[9,18],\"5\":[9,14]}.","propertyNames":{"pattern":"^[0-6]$"},"additionalProperties":{"type":"array","prefixItems":[{"type":"integer","minimum":0,"maximum":23},{"type":"integer","minimum":1,"maximum":24}],"minItems":2,"maxItems":2}},"AgentPatch":{"type":"object","additionalProperties":false,"description":"Customer-editable business fields. Provider settings, transfer_number, plan limits, and internal behavior are not writable. ATOMIC REPLACEMENT WARNING: hours, menu, products, services, and listings are complete datasets. Supplying any one of these fields replaces that field wholesale; omitted entries are deleted rather than merged. Read the current agent, modify the complete field, then send the replacement.","x-atomic-replacement-fields":["hours","menu","products","services","listings"],"properties":{"business":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string","format":"uri"},"hours_human":{"type":"string"},"shipping_human":{"type":"string"},"returns_human":{"type":"string"},"zones_human":{"type":"string"}}},"assistant":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"greeting":{"type":"string"}}},"voice":{"type":"object","additionalProperties":false,"description":"Opaque Vexium voice IDs returned by GET /voices.","properties":{"es":{"type":"string"},"en":{"type":"string"}}},"prompt_extra":{"type":"string"},"services":{"type":"array","items":{"type":"object"}},"menu":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"specials":{"type":"string"},"dietary":{"type":"string"},"policy":{"type":"string"},"products":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"listings":{"type":"array","items":{"type":"object"}},"hours":{"type":"object","description":"Weekly structured hours. Keys are weekday numbers as strings (0=Monday through 6=Sunday); each value is [opening_hour, closing_hour] using whole hours on a 24-hour clock. Omit a day to mark it closed. Example: {\"0\":[9,18],\"5\":[9,14]}.","propertyNames":{"pattern":"^[0-6]$"},"additionalProperties":{"type":"array","prefixItems":[{"type":"integer","minimum":0,"maximum":23},{"type":"integer","minimum":1,"maximum":24}],"minItems":2,"maxItems":2}}}},"AgentPatchRequest":{"description":"ATOMIC REPLACEMENT WARNING: hours, menu, products, services, and listings are complete datasets. Supplying any one of these fields replaces that field wholesale; omitted entries are deleted rather than merged. Read the current agent, modify the complete field, then send the replacement.","oneOf":[{"$ref":"#/components/schemas/AgentPatch"},{"type":"object","additionalProperties":false,"required":["config"],"properties":{"config":{"$ref":"#/components/schemas/AgentPatch"}}}]},"AgentConfig":{"type":"object","description":"Customer-visible business configuration. Editable fields follow AgentPatch.","properties":{"business":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string","format":"uri"},"hours_human":{"type":"string"},"shipping_human":{"type":"string"},"returns_human":{"type":"string"},"zones_human":{"type":"string"}}},"assistant":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"greeting":{"type":"string"}}},"voice":{"type":"object","additionalProperties":false,"description":"Opaque Vexium voice IDs returned by GET /voices.","properties":{"es":{"type":"string"},"en":{"type":"string"}}},"prompt_extra":{"type":"string"},"services":{"type":"array","items":{"type":"object"}},"menu":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"specials":{"type":"string"},"dietary":{"type":"string"},"policy":{"type":"string"},"products":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"listings":{"type":"array","items":{"type":"object"}},"hours":{"type":"object","description":"Weekly structured hours. Keys are weekday numbers as strings (0=Monday through 6=Sunday); each value is [opening_hour, closing_hour] using whole hours on a 24-hour clock. Omit a day to mark it closed. Example: {\"0\":[9,18],\"5\":[9,14]}.","propertyNames":{"pattern":"^[0-6]$"},"additionalProperties":{"type":"array","prefixItems":[{"type":"integer","minimum":0,"maximum":23},{"type":"integer","minimum":1,"maximum":24}],"minItems":2,"maxItems":2}}},"additionalProperties":true},"Agent":{"type":"object","description":"Customer-safe resolved business configuration; never includes provider credentials.","required":["slug","vertical","display_name","status","config"],"properties":{"slug":{"type":"string"},"vertical":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"config":{"$ref":"#/components/schemas/AgentConfig"},"demo_fixtures":{"type":"boolean"}},"additionalProperties":true},"Voice":{"type":"object","required":["id","name","language"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string","enum":["es","en"]},"gender":{"type":"string"},"description":{"type":"string"},"recommended":{"type":"boolean"}}},"Call":{"type":"object","required":["id","object","started_at","duration_seconds","language","outcome","channel"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"call"},"started_at":{"type":"string","format":"date-time"},"duration_seconds":{"type":"integer","minimum":0},"language":{"type":"string"},"outcome":{"type":"string","enum":["booking","info","handoff","abandoned","error","over_limit"]},"channel":{"type":"string","enum":["web","phone"]},"summary":{}}},"CallDetail":{"allOf":[{"$ref":"#/components/schemas/Call"},{"type":"object","properties":{"transcript":{}}}]},"Capture":{"type":"object","required":["id","object","kind","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"capture"},"kind":{"type":"string"},"customer_name":{"type":"string"},"customer_phone":{"type":"string"},"scheduled_at":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?$","examples":["2026-08-17T14:30:00"]},{"type":"null"}],"description":"Nullable business-local date and time string without a timezone offset."},"service":{"type":"string"},"confirmation_code":{"type":"string"},"status":{"type":"string","enum":["pending_confirm","confirmed","cancelled","no_show"]},"created_at":{"type":"string","format":"date-time"}}},"ConnectionInput":{"type":"object","additionalProperties":false,"required":["name","url","events"],"properties":{"type":{"type":"string","enum":["crm.outbound"],"default":"crm.outbound"},"name":{"type":"string","maxLength":60},"url":{"type":"string","format":"uri","pattern":"^https://","description":"Public HTTPS destination on port 443. Userinfo, redirects, private, loopback, link-local, and internal addresses are rejected."},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["capture.created","call.completed"]}}}},"ConnectionPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","maxLength":60},"url":{"type":"string","format":"uri","pattern":"^https://","description":"Public HTTPS destination on port 443. Userinfo, redirects, private, loopback, link-local, and internal addresses are rejected."},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["capture.created","call.completed"]}}}},"Connection":{"type":"object","required":["id","type","name","url","events","status","livemode","secret_prefix"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"disabled_by":{"type":"string"},"disabled_reason":{"type":"string"},"livemode":{"type":"boolean"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"secret_prefix":{"type":"string"},"secret_set_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"secret_grace_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","readOnly":true,"description":"Returned only on creation or rotation."},"secret_notice":{"type":"string"},"deliveries":{"type":"object"}}},"Delivery":{"type":"object","required":["id","connection_id","event","status","attempts","livemode","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","delivering","delivered","failed","dead"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error_code":{"type":"string"},"message":{"type":"string"},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"Document":{"type":"object","required":["id","title","kind","size_bytes","status","fragments","livemode"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"kind":{"type":"string"},"size_bytes":{"type":"integer"},"status":{"type":"string","enum":["pending","processing","ready","error","archived"]},"status_label":{"type":"string"},"status_help":{"type":"string"},"fragments":{"type":"integer"},"livemode":{"type":"boolean"},"agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ready_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Insufficient scope, protected field, or live-only write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Missing resource or resource outside the credential tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PayloadTooLarge":{"description":"Request body or uploaded document exceeds its limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadGateway":{"description":"A required upstream storage operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServiceUnavailable":{"description":"The account database is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"x-vexium-scopes":[{"scope":"agents:read","label":"Leer agentes","description":"Ver la configuración de negocio de tus recepcionistas (datos, horarios, servicios). Nunca su comportamiento interno.","resource":"agents","access":"read","available_in_test_mode":true},{"scope":"agents:write","label":"Editar agentes","description":"Actualizar los datos de tu negocio: horarios, servicios, menú, políticas y la voz (del catálogo Vexium). No incluye el comportamiento del agente ni los límites de tu plan.","resource":"agents","access":"write","available_in_test_mode":false},{"scope":"calls:read","label":"Leer llamadas","description":"Historial de llamadas: duración, idioma, resultado y transcripción.","resource":"calls","access":"read","available_in_test_mode":true},{"scope":"captures:read","label":"Leer citas y leads","description":"Las citas y los leads que capta tu recepcionista.","resource":"captures","access":"read","available_in_test_mode":true},{"scope":"captures:write","label":"Gestionar citas y leads","description":"Confirmar, cancelar o marcar como no presentada una cita.","resource":"captures","access":"write","available_in_test_mode":false},{"scope":"connections:read","label":"Leer conexiones","description":"Ver tus webhooks de entrega y su historial de envíos.","resource":"connections","access":"read","available_in_test_mode":true},{"scope":"connections:write","label":"Gestionar conexiones","description":"Dar de alta, editar y desactivar los destinos a los que te entregamos citas y leads.","resource":"connections","access":"write","available_in_test_mode":true},{"scope":"knowledge:read","label":"Leer base de conocimiento","description":"Consultar lo que sabe tu recepcionista.","resource":"knowledge","access":"read","available_in_test_mode":true},{"scope":"knowledge:write","label":"Editar base de conocimiento","description":"Añadir, actualizar y retirar contenido de la base de conocimiento.","resource":"knowledge","access":"write","available_in_test_mode":false},{"scope":"usage:read","label":"Leer consumo","description":"Minutos y llamadas consumidos por periodo, y los límites de tu plan.","resource":"usage","access":"read","available_in_test_mode":true}],"x-vexium-pagination":{"default_limit":25,"maximum_limit":100,"cursor_parameter":"starting_after","envelope_schema":"#/components/schemas/ListEnvelope"}}