{"openapi":"3.1.0","info":{"title":"Agent Telco API","version":"1.0.0","description":"A REST API for agents to manage mobile numbers, exchange SMS and delegate voice calls."},"servers":[{"url":"https://www.agenttelco.com"}],"tags":[{"name":"System","description":"API service status."},{"name":"Readiness","description":"Workspace capability gates and included usage."},{"name":"Numbers","description":"Mobile-number lifecycle operations."},{"name":"Number operations","description":"Durable status and recovery for number provisioning."},{"name":"Messages","description":"Inbound and outbound SMS operations."},{"name":"Webhooks","description":"Signed customer event delivery and replay."}],"paths":{"/api/v1/agents":{"get":{"operationId":"listAgents","summary":"List saved agents","description":"Saved agent versions are immutable. Calls pin a version when queued; edits affect future calls. Workspace call permissions apply.","tags":["Agents"],"responses":{"200":{"description":"Current saved agent versions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archived_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"description":{"type":"string","maxLength":160},"preview_truncated":{"type":"boolean"}},"required":["name","id","version","created_at","updated_at","archived_at","description","preview_truncated"],"additionalProperties":false}},"meta":{"type":"object","properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["next_cursor","has_more"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":20,"description":"Agents per page: 1–100; default 20.","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"},"post":{"operationId":"createAgent","summary":"Create a saved agent","description":"Saved agent versions are immutable. Calls pin a version when queued; edits affect future calls. Workspace call permissions apply.","tags":["Agents"],"responses":{"201":{"description":"Created agent.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"required":["instructions","model","voice","language","speech_mode","voicemail","max_duration_seconds","allowed_tools","mcp_connections"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archived_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["name","config","id","version","created_at","updated_at","archived_at"],"additionalProperties":false}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"default":{},"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"additionalProperties":false}},"required":["name"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"}},"/api/v1/agents/{agentId}":{"get":{"operationId":"getAgent","summary":"Inspect a saved agent","description":"Saved agent versions are immutable. Calls pin a version when queued; edits affect future calls. Workspace call permissions apply.","tags":["Agents"],"responses":{"200":{"description":"Saved agent version.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"required":["instructions","model","voice","language","speech_mode","voicemail","max_duration_seconds","allowed_tools","mcp_connections"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archived_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["name","config","id","version","created_at","updated_at","archived_at"],"additionalProperties":false}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"},"patch":{"operationId":"updateAgent","summary":"Save a new agent version","description":"Saved agent versions are immutable. Calls pin a version when queued; edits affect future calls. Workspace call permissions apply.","tags":["Agents"],"responses":{"200":{"description":"New immutable agent version.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"required":["instructions","model","voice","language","speech_mode","voicemail","max_duration_seconds","allowed_tools","mcp_connections"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archived_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["name","config","id","version","created_at","updated_at","archived_at"],"additionalProperties":false}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"additionalProperties":false},"expected_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expected_version"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"},"delete":{"operationId":"archiveAgent","summary":"Archive a saved agent","description":"Saved agent versions are immutable. Calls pin a version when queued; edits affect future calls. Workspace call permissions apply.","tags":["Agents"],"responses":{"200":{"description":"Archived agent. Existing calls keep their pinned config.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"config":{"type":"object","properties":{"instructions":{"type":"string","minLength":10,"maxLength":8000},"model":{"type":"string","enum":["gpt-realtime-mini-2025-12-15","gpt-realtime-2025-08-28"]},"voice":{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},"language":{"type":"string","pattern":"^[a-z]{2,3}(?:-[A-Z]{2})?$"},"speech_mode":{"type":"string","enum":["conversational","silent"]},"voicemail":{"type":"string","enum":["hang_up","leave_message"]},"max_duration_seconds":{"type":"integer","minimum":30,"maximum":240},"allowed_tools":{"maxItems":4,"type":"array","items":{"type":"string","enum":["send_dtmf","finish_call","request_input","listen"]}},"mcp_connections":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"connection_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tool_names":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"}}},"required":["connection_id","tool_names"]}}},"required":["instructions","model","voice","language","speech_mode","voicemail","max_duration_seconds","allowed_tools","mcp_connections"]},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"archived_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["name","config","id","version","created_at","updated_at","archived_at"],"additionalProperties":false}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"}},"/api/v1/mcp-connections":{"get":{"operationId":"listMcpConnections","summary":"Inspect available remote MCP connections","description":"Returns connection IDs, names, tool descriptions, call directions and informational annotations. Workspace administrators configure or revoke credentials in the human console.","tags":["Agents"],"responses":{"200":{"description":"Remote connections without secrets.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9_.-]{1,64}$"},"description":{"default":"","type":"string","maxLength":1000},"direction":{"default":"outbound","type":"string","enum":["outbound","inbound","both"]},"annotations":{"type":"object","properties":{"readOnlyHint":{"type":"boolean"},"destructiveHint":{"type":"boolean"}}}},"required":["name"]}}},"required":["id","name","tools"]}}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"}},"/api/v1/numbers/{numberId}/inbound-route":{"get":{"operationId":"getInboundRoute","summary":"Read an incoming call plan and answering status","description":"Read or save a number's incoming call plan. Saving an agent plan verifies the number and starts answering immediately. When answering.customer_pricing is priced, pass its pricing_version as customer_pricing_version; answered calls are charged at it. Saving mode disabled stops answering. Omit agent_version to use the agent's latest version for each new call.","tags":["Numbers"],"responses":{"200":{"description":"The number's incoming call routing plan.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"config":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"disabled"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"agent"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agent_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"availability":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"closed"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"weekly"},"timezone":{"type":"string","minLength":1,"maxLength":80},"windows":{"minItems":1,"maxItems":28,"type":"array","items":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":7},"start_minute":{"type":"integer","minimum":0,"maximum":1439},"end_minute":{"type":"integer","minimum":1,"maximum":1440}},"required":["day","start_minute","end_minute"],"additionalProperties":false}}},"required":["mode","timezone","windows"],"additionalProperties":false}]},"fallback":{"type":"string","enum":["existing_human","reject"]}},"required":["mode","agent_id","availability","fallback"],"additionalProperties":false}]},"transfer_available":{"type":"boolean","const":false},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"answering":{"type":"object","properties":{"status":{"type":"string","enum":["on","off","blocked"]},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"customer_pricing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"free"},"customer_acceptance_required":{"type":"boolean","const":false}},"required":["mode","customer_acceptance_required"]},{"type":"object","properties":{"mode":{"type":"string","const":"priced"},"customer_acceptance_required":{"type":"boolean","const":true},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"connection_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"rate_micros_per_minute":{"type":"integer","minimum":0,"maximum":9007199254740991},"minimum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"billing_increment_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","enum":["bundled_connected_time","carrier_connected_time"]}},"required":["mode","customer_acceptance_required","pricing_version","currency","connection_micros","rate_micros_per_minute","billing_increment_seconds","maximum_connected_seconds","maximum_charge_micros","basis"]}]},"accepted_pricing":{"anyOf":[{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"free"},"customer_acceptance_required":{"type":"boolean","const":false}},"required":["mode","customer_acceptance_required"]},{"type":"object","properties":{"mode":{"type":"string","const":"priced"},"customer_acceptance_required":{"type":"boolean","const":true},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"connection_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"rate_micros_per_minute":{"type":"integer","minimum":0,"maximum":9007199254740991},"minimum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"billing_increment_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","enum":["bundled_connected_time","carrier_connected_time"]}},"required":["mode","customer_acceptance_required","pricing_version","currency","connection_micros","rate_micros_per_minute","billing_increment_seconds","maximum_connected_seconds","maximum_charge_micros","basis"]}]},{"type":"null"}]}},"required":["status","blockers","customer_pricing","accepted_pricing"]}},"required":["number_id","revision","config","transfer_available","updated_at","answering"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"},"put":{"operationId":"updateInboundRoute","summary":"Save an incoming call plan and set answering","description":"Read or save a number's incoming call plan. Saving an agent plan verifies the number and starts answering immediately. When answering.customer_pricing is priced, pass its pricing_version as customer_pricing_version; answered calls are charged at it. Saving mode disabled stops answering. Omit agent_version to use the agent's latest version for each new call. Requires numbers:write and calls:write permission for the acting user. Connections also need both scopes, number access and number-management permission. This sets up provider routing when needed. Use expected_revision 0 for a new plan; stale writes return 409.","tags":["Numbers"],"responses":{"200":{"description":"The number's incoming call routing plan.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"config":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"disabled"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"agent"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agent_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"availability":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"closed"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"weekly"},"timezone":{"type":"string","minLength":1,"maxLength":80},"windows":{"minItems":1,"maxItems":28,"type":"array","items":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":7},"start_minute":{"type":"integer","minimum":0,"maximum":1439},"end_minute":{"type":"integer","minimum":1,"maximum":1440}},"required":["day","start_minute","end_minute"],"additionalProperties":false}}},"required":["mode","timezone","windows"],"additionalProperties":false}]},"fallback":{"type":"string","enum":["existing_human","reject"]}},"required":["mode","agent_id","availability","fallback"],"additionalProperties":false}]},"transfer_available":{"type":"boolean","const":false},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"answering":{"type":"object","properties":{"status":{"type":"string","enum":["on","off","blocked"]},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"customer_pricing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"free"},"customer_acceptance_required":{"type":"boolean","const":false}},"required":["mode","customer_acceptance_required"]},{"type":"object","properties":{"mode":{"type":"string","const":"priced"},"customer_acceptance_required":{"type":"boolean","const":true},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"connection_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"rate_micros_per_minute":{"type":"integer","minimum":0,"maximum":9007199254740991},"minimum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"billing_increment_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","enum":["bundled_connected_time","carrier_connected_time"]}},"required":["mode","customer_acceptance_required","pricing_version","currency","connection_micros","rate_micros_per_minute","billing_increment_seconds","maximum_connected_seconds","maximum_charge_micros","basis"]}]},"accepted_pricing":{"anyOf":[{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"free"},"customer_acceptance_required":{"type":"boolean","const":false}},"required":["mode","customer_acceptance_required"]},{"type":"object","properties":{"mode":{"type":"string","const":"priced"},"customer_acceptance_required":{"type":"boolean","const":true},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"connection_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"rate_micros_per_minute":{"type":"integer","minimum":0,"maximum":9007199254740991},"minimum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"billing_increment_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","enum":["bundled_connected_time","carrier_connected_time"]}},"required":["mode","customer_acceptance_required","pricing_version","currency","connection_micros","rate_micros_per_minute","billing_increment_seconds","maximum_connected_seconds","maximum_charge_micros","basis"]}]},{"type":"null"}]}},"required":["status","blockers","customer_pricing","accepted_pricing"]}},"required":["number_id","revision","config","transfer_available","updated_at","answering"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"config":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"disabled"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"agent"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agent_version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"availability":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"always"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"closed"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"weekly"},"timezone":{"type":"string","minLength":1,"maxLength":80},"windows":{"minItems":1,"maxItems":28,"type":"array","items":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":7},"start_minute":{"type":"integer","minimum":0,"maximum":1439},"end_minute":{"type":"integer","minimum":1,"maximum":1440}},"required":["day","start_minute","end_minute"],"additionalProperties":false}}},"required":["mode","timezone","windows"],"additionalProperties":false}]},"fallback":{"type":"string","enum":["existing_human","reject"]}},"required":["mode","agent_id","availability","fallback"],"additionalProperties":false}]},"customer_pricing_version":{"type":"string","minLength":1,"maxLength":200}},"required":["expected_revision","config"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:write"]}],"x-required-scope":"numbers:write"}},"/api/v1/numbers/{numberId}/voice-routing":{"post":{"operationId":"configureVoiceRouting","summary":"Set up a number for incoming calls","description":"Configure this workspace number's carrier and voice routing while preserving SMS. Does not enable AI answering. Requires number-management permission and calls:read for agent connections.","tags":["Numbers"],"responses":{"200":{"description":"Number routing configured.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"configured":{"type":"boolean","const":true}},"required":["configured"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:write"]}],"x-required-scope":"numbers:write"}},"/api/v1/calls/prepare":{"post":{"operationId":"prepareCall","summary":"Prepare a call without placing it","description":"Checks destination, caller number, permissions and admission readiness. Returns current pricing and the selected agent version. No credit is reserved. Accept pricing when customer_acceptance_required is true; execution rechecks permissions and funding.","tags":["Calls"],"responses":{"200":{"description":"Call preparation and blockers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"pricing":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"free"},"customer_acceptance_required":{"type":"boolean","const":false}},"required":["mode","customer_acceptance_required"]},{"type":"object","properties":{"mode":{"type":"string","const":"priced"},"customer_acceptance_required":{"type":"boolean","const":true},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"connection_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"rate_micros_per_minute":{"type":"integer","minimum":0,"maximum":9007199254740991},"minimum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"billing_increment_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_connected_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maximum_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"basis":{"type":"string","enum":["bundled_connected_time","carrier_connected_time"]}},"required":["mode","customer_acceptance_required","pricing_version","currency","connection_micros","rate_micros_per_minute","billing_increment_seconds","maximum_connected_seconds","maximum_charge_micros","basis"]}]},"agent":{"type":"object","properties":{"agent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"agent_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"max_duration_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"commands":{"type":"array","items":{"type":"string","enum":["steer","reply","dtmf","silence","resume"]}}},"required":["agent_id","agent_version","max_duration_seconds","commands"]}},"required":["ready","blockers","to","from","pricing","agent"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"result_fields":{"description":"Up to 8 fields with unique keys. Omit for a summary only.","maxItems":8,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"description":{"type":"string","minLength":1,"maxLength":200},"type":{"description":"Defaults to string. Check get_account capabilities.voice.result_types first. Specify currency and units for money.","type":"string","enum":["string","boolean","number","integer"]},"format":{"description":"String fields only. Check capabilities.voice.result_formats in get_account.","type":"string","enum":["date","time","date-time"]}},"required":["key","description"]}},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agent_version":{"description":"Positive version returned by prepare_call; requires agent_id.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"speech_mode":{"type":"string","const":"silent"}},"required":["to"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"}},"/api/v1/calls/{callId}/events":{"get":{"operationId":"waitForCall","summary":"Wait for meaningful call events","description":"Outbound calls only. Connection-scoped and permission checked. Events are retained with the call; omit after to replay. Commands report accepted, applied, rejected or uncertain. Never retry an uncertain action with a new key.","tags":["Calls"],"responses":{"200":{"description":"Wait for meaningful call events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"progress"},"data":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":500}},"required":["message"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"input_requested"},"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"question":{"type":"string","minLength":1,"maxLength":1000},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120},"fallback":{"type":"string","enum":["continue","hang_up"]}},"required":["request_id","question","timeout_seconds","fallback"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"tool_execution"},"data":{"type":"object","properties":{"tool":{"type":"string","minLength":1,"maxLength":80},"invocation_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["executed","failed","uncertain"]},"digits":{"type":"string","maxLength":20},"completed_digits":{"type":"string","maxLength":20},"evidence":{"type":"string","enum":["livekit_publish_ack","tool_result"]},"summary":{"type":"string","maxLength":500}},"required":["tool","status"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"termination"},"data":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":200},"disconnect_source":{"type":"string","enum":["room","sip_participant"]},"disconnect_reason":{"type":"string","maxLength":80}},"required":["reason"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"speech_mode"},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["silent","conversational"]}},"required":["mode"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"context_updated"},"data":{"type":"object","properties":{"command_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["command_id"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"transcript"},"data":{"type":"object","properties":{"speaker":{"type":"string","enum":["agent","remote"]},"text":{"type":"string","minLength":1,"maxLength":500}},"required":["speaker","text"],"additionalProperties":false},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"state_changed"},"data":{"type":"object","properties":{"state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["state"]},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]},{"type":"object","properties":{"type":{"type":"string","const":"command_status"},"data":{"type":"object","properties":{"command_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["steer","reply","dtmf","silence","resume"]},"status":{"type":"string","enum":["accepted","applied","rejected","uncertain"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["command_id","type","status"]},"cursor":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","data","cursor","created_at"]}]}},"call":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state"]},"meta":{"type":"object","properties":{"resume_cursor":{"type":"string"},"done":{"type":"boolean","description":"True when execution ended and the event backlog is drained."},"timed_out":{"type":"boolean"}},"required":["resume_cursor","done","timed_out"]}},"required":["data","call","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"callId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"description":"Events per page: 1–50; default 20.","type":"integer","minimum":1,"maximum":50}},{"name":"wait_seconds","in":"query","required":false,"schema":{"default":0,"description":"Wait 0–25 seconds; 0 returns immediately.","type":"integer","minimum":0,"maximum":25}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"}},"/api/v1/calls/{callId}/commands":{"post":{"operationId":"submitCallCommand","summary":"Submit an idempotent call command","description":"Outbound calls only. Connection-scoped and permission checked. Commands report accepted, applied, rejected or uncertain. Never retry an uncertain action with a new key.","tags":["Calls"],"responses":{"200":{"description":"Submit an idempotent call command","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"command":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"steer"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"reply"},"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["type","request_id","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"dtmf"},"digits":{"type":"string","pattern":"^[0-9*#]{1,20}$"}},"required":["type","digits"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"silence"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"resume"}},"required":["type"],"additionalProperties":false}]},"status":{"type":"string","enum":["accepted","applied","rejected","uncertain"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"acknowledged_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"dispatched_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","command","status","reason","created_at","acknowledged_at","dispatched_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"callId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idempotency_key":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"command":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"steer"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"reply"},"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["type","request_id","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"dtmf"},"digits":{"type":"string","pattern":"^[0-9*#]{1,20}$"}},"required":["type","digits"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"silence"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"resume"}},"required":["type"],"additionalProperties":false}]}},"required":["idempotency_key","command"]}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"}},"/api/v1/calls":{"post":{"operationId":"startCall","summary":"Request a delegated phone call","description":"The connection needs call permission. Calls run asynchronously with fixed duration, destination and budget limits. Reuse the same idempotency key after timeouts. Results contain model-generated summaries, not verified facts.","tags":["Calls"],"responses":{"202":{"description":"Delegated call response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state"]},"meta":{"type":"object","properties":{"resume_cursor":{"type":"string"}},"required":["resume_cursor"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"task":{"type":"string","minLength":10,"maxLength":2000,"description":"Task instructions, 10–2000 characters."},"result_fields":{"description":"Up to 8 fields with unique keys. Omit for a summary only.","maxItems":8,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"description":{"type":"string","minLength":1,"maxLength":200},"type":{"description":"Defaults to string. Check get_account capabilities.voice.result_types first. Specify currency and units for money.","type":"string","enum":["string","boolean","number","integer"]},"format":{"description":"String fields only. Check capabilities.voice.result_formats in get_account.","type":"string","enum":["date","time","date-time"]}},"required":["key","description"]}},"speech_mode":{"type":"string","const":"silent"},"agent_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"agent_version":{"description":"Positive version returned by prepare_call; requires agent_id.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"context":{"description":"Background information, up to 2000 characters.","type":"string","maxLength":2000},"customer_pricing_version":{"description":"Required when prepare_call pricing.customer_acceptance_required is true. Pass the explicitly accepted pricing_version; omit for free.","type":"string","minLength":1,"maxLength":120},"idempotency_key":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["from","to","task","idempotency_key"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"},"get":{"operationId":"listCalls","summary":"List visible inbound and outbound calls","description":"Lists this connection's outbound calls and incoming AI calls on numbers it can access. Omit direction for both. A cursor pages the combined history newest first. Results contain model-generated summaries, not verified facts.","tags":["Calls"],"responses":{"200":{"description":"Call summaries and the next combined-history cursor.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string"},"to":{"type":"string"},"task_preview":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"preview_truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"outcome":{"anyOf":[{"type":"string","enum":["succeeded","incomplete","unanswered","failed"]},{"type":"null"}]},"answered_by":{"anyOf":[{"type":"string","enum":["person","voicemail","unknown","not_answered"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"ended_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state","direction","from","to","task_preview","preview_truncated","outcome","answered_by","created_at","ended_at"]}},"meta":{"type":"object","properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["next_cursor","has_more"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"description":"Calls per page: 1–50; default 10.","type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"lifecycle_state","in":"query","required":false,"schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]}},{"name":"created_after","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},{"name":"created_before","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"}},"/api/v1/calls/{callId}":{"get":{"operationId":"getCall","summary":"Get a visible call and its result","description":"Returns this connection's outbound call or an incoming AI call on a number it can access. Results contain model-generated summaries, not verified facts.","tags":["Calls"],"responses":{"200":{"description":"Outbound or inbound call detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."},"direction":{"type":"string","const":"outbound"},"from":{"type":"string"},"to":{"type":"string"},"task":{"type":"string"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"connected_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"agent":{"anyOf":[{"type":"object","properties":{"agent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"agent_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["agent_id","agent_version"]},{"type":"null"}]},"result":{"anyOf":[{"type":"object","properties":{"answered_by":{"type":"string","enum":["person","voicemail","unknown","not_answered"]},"termination_reason":{"type":"string","maxLength":200},"evidence_source":{"type":"string","enum":["model_report","runtime_observation"]},"outcome":{"type":"string","enum":["succeeded","incomplete","unanswered","failed"]},"summary":{"type":"string","maxLength":2000},"findings":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}},"answers":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]},{"type":"null"}]}},"required":["key","value"]}}},"required":["outcome","summary","findings"]},{"type":"null"}]},"duration":{"anyOf":[{"type":"object","properties":{"seconds":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","const":"worker_sip","description":"Elapsed time after the worker observed active SIP. May precede confirmation in the carrier record; not a billed duration."}},"required":["seconds","source"]},{"type":"null"}]},"customer_charge":{"anyOf":[{"oneOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["reserved","uncertain"]},"charged_micros":{"type":"null"}},"required":["currency","reserved_micros","status","charged_micros"]},{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","const":"settled"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","reserved_micros","status","charged_micros"]}]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"ended_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state","direction","from","to","task","agent_name","connected_at","agent","result","duration","customer_charge","created_at","ended_at"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."},"direction":{"type":"string","const":"inbound"},"from":{"type":"string"},"to":{"type":"string"},"task":{"type":"null"},"agent":{"type":"object","properties":{"agent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"agent_version":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["agent_id","agent_version"]},"result":{"anyOf":[{"type":"object","properties":{"answered_by":{"type":"string","enum":["person","voicemail","unknown","not_answered"]},"termination_reason":{"type":"string","maxLength":200},"evidence_source":{"type":"string","enum":["model_report","runtime_observation"]},"outcome":{"type":"string","enum":["succeeded","incomplete","unanswered","failed"]},"summary":{"type":"string","maxLength":2000},"findings":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}},"answers":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":500},{"type":"number"},{"type":"boolean"}]},{"type":"null"}]}},"required":["key","value"]}}},"required":["outcome","summary","findings"]},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"usage":{"anyOf":[{"type":"object","properties":{"report":{"type":"object","properties":{"revision":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"final":{"type":"boolean"},"complete":{"type":"boolean"},"connected_seconds":{"anyOf":[{"type":"integer","minimum":0,"maximum":600},{"type":"null"}]},"models":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":100},"requests":{"type":"integer","minimum":0,"maximum":256},"input_text_tokens":{"type":"integer","minimum":0,"maximum":10000000},"input_audio_tokens":{"type":"integer","minimum":0,"maximum":10000000},"cached_input_text_tokens":{"type":"integer","minimum":0,"maximum":10000000},"cached_input_audio_tokens":{"type":"integer","minimum":0,"maximum":10000000},"output_text_tokens":{"type":"integer","minimum":0,"maximum":10000000},"output_audio_tokens":{"type":"integer","minimum":0,"maximum":10000000}},"required":["model","requests","input_text_tokens","input_audio_tokens","cached_input_text_tokens","cached_input_audio_tokens","output_text_tokens","output_audio_tokens"]}},"diagnostics":{"type":"object","properties":{"issues":{"maxItems":10,"type":"array","items":{"type":"string","enum":["capacity_exceeded","invalid_usage","model_mismatch","invalid_event","transcription_failed","provider_error","session_error","call_failed","close_failed","unknown"]}},"ignored_cancellations":{"type":"integer","minimum":0,"maximum":256},"pending":{"type":"object","properties":{"realtime":{"type":"integer","minimum":0,"maximum":10000000},"transcription":{"type":"integer","minimum":0,"maximum":10000000},"summary":{"type":"integer","minimum":0,"maximum":10000000}},"required":["realtime","transcription","summary"]}},"required":["issues","pending"]}},"required":["revision","final","complete","connected_seconds","models"]},"pricing_version":{"type":"string"},"openai":{"type":"object","properties":{"currency":{"type":"string","const":"USD"},"estimated_cost_micros":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"observed_cost_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"billed_cost_micros":{"type":"null"}},"required":["currency","estimated_cost_micros","observed_cost_micros","billed_cost_micros"]},"carrier":{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"estimated_cost_micros":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"billed_cost_micros":{"type":"null"}},"required":["currency","estimated_cost_micros","billed_cost_micros"]}},"required":["report","pricing_version","openai","carrier"]},{"type":"null"}]},"customer_charge":{"anyOf":[{"oneOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["reserved","uncertain"]},"charged_micros":{"type":"null"}},"required":["currency","reserved_micros","status","charged_micros"]},{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","const":"settled"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","reserved_micros","status","charged_micros"]}]},{"type":"null"}]},"duration":{"anyOf":[{"type":"object","properties":{"seconds":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","const":"worker_sip","description":"Elapsed time after the worker observed active SIP. May precede confirmation in the carrier record; not a billed duration."}},"required":["seconds","source"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"ended_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state","direction","from","to","task","agent","result","failure","usage","customer_charge","duration","created_at","ended_at"]}]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"callId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:read"]}],"x-required-scope":"calls:read"},"delete":{"operationId":"cancelCall","summary":"Cancel a delegated call","description":"Outbound calls only. Cancels this connection's queued or running call.","tags":["Calls"],"responses":{"200":{"description":"Delegated call response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"call_state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Carrier state; null means unknown."},"connection_confirmed":{"type":"boolean","description":"Carrier connection evidence, not person detection. False means unconfirmed."},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"lifecycle_state":{"type":"string","enum":["queued","running","completed","failed","cancelled"],"description":"Execution progress; completed does not imply task success. See result.outcome."},"cancellation_status":{"type":"string","enum":["accepted","already_terminal"]}},"required":["id","call_state","connection_confirmed","failure_code","lifecycle_state","cancellation_status"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"callId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["calls:write"]}],"x-required-scope":"calls:write"}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Check API health","description":"Checks whether the Agent Telco API is serving requests.","tags":["System"],"responses":{"200":{"description":"The API is healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"service":{"type":"string","const":"agenttelco"},"status":{"type":"string","const":"ok"},"version":{"type":"string","const":"v1"}},"required":["service","status","version"]}},"required":["data"]}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/api/v1/account":{"get":{"operationId":"getAccount","summary":"Get account and connection access","description":"Returns this connection's effective permissions, workspace credit and actionable blockers. Purchase readiness is for the cheapest term; the chosen quote and message body determine actual cost. Mutations recheck authorization and funding.","tags":["Account"],"responses":{"200":{"description":"Account and connection access.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"limits":{"type":"object","properties":{"numbers":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["default","override"]},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["value","source","used"]},"sms_segments_per_month":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["default","override"]},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["value","source","used"]},"provider_spend_micros_per_month":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["default","override"]},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["value","source","used"]},"api_requests_per_minute":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["default","override"]}},"required":["value","source"]},"concurrent_calls":{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["default","override"]},"used":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["value","source","used"]}},"required":["numbers","sms_segments_per_month","provider_spend_micros_per_month","api_requests_per_minute","concurrent_calls"]},"workspace":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]}},"required":["id","status"]},"connection":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"credit":{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"available_micros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["currency","available_micros"]},"capabilities":{"type":"object","properties":{"voice":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}},"result_types":{"type":"array","items":{"type":"string","enum":["string","boolean","number","integer"]},"description":"Current worker support; empty when unavailable or unknown."},"result_formats":{"type":"array","items":{"type":"string","enum":["date","time","date-time"]},"description":"Supported string formats. Empty means no formatted fields."}},"required":["allowed","blockers","result_types","result_formats"]},"read_numbers":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]},"quote_numbers":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]},"purchase_numbers":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]},"manage_numbers":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]},"read_messages":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]},"send_messages":{"type":"object","properties":{"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether waiting and repeating preparation may help. Never start a replacement call to recover an uncertain outcome."},"action_url":{"type":"string"}},"required":["code","message","retryable"]}}},"required":["allowed","blockers"]}},"required":["voice","read_numbers","quote_numbers","purchase_numbers","manage_numbers","read_messages","send_messages"]},"links":{"type":"object","properties":{"credit":{"type":"string"},"connections":{"type":"string"}},"required":["credit","connections"]}},"required":["limits","workspace","connection","credit","capabilities","links"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["readiness:read"]}],"x-required-scope":"readiness:read"}},"/api/v1/numbers":{"get":{"operationId":"listNumbers","summary":"List mobile numbers","description":"Lists the workspace's unreleased mobile numbers and their current status.","tags":["Numbers"],"responses":{"200":{"description":"The workspace's unreleased mobile numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]}}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"},"post":{"operationId":"provisionNumber","summary":"Provision a mobile number","description":"Purchases one number using quote_id in the request body. One quote authorizes at most one purchase and spends the quoted credit. Reuse the same quote_id after a timeout. A 202 response is addressable through Location and must not be replaced with a new order key.","tags":["Numbers"],"responses":{"200":{"description":"A replay of a completed number order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"201":{"description":"A newly provisioned mobile number.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"202":{"description":"The order is still processing, needs attention, or has an uncertain provider outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","const":"number_provisioning"},"status":{"type":"string","enum":["pending","processing","attention","uncertain","succeeded","failed"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","inbound_setup_incomplete","operation_failed"]},{"type":"null"}]},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"idempotency_key":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","type","status","status_reason","number_id","idempotency_key","created_at","updated_at"]},"meta":{"type":"object","properties":{"location":{"type":"string"},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["location","retry_after_seconds"]}},"required":["data"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"An active, current billing entitlement is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The telecom provider could not complete the operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Accepted quote ID. One quote purchases at most one number. Reuse it after a timeout."}},"required":["quote_id"]}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:write"]}],"x-required-scope":"numbers:write"}},"/api/v1/numbers/{numberId}":{"get":{"operationId":"getNumber","summary":"Get a mobile number","description":"Gets one workspace-owned mobile number, including setup or release attention state.","tags":["Numbers"],"responses":{"200":{"description":"The mobile number.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"},"patch":{"operationId":"updateNumber","summary":"Change number auto-renew","description":"Turn credit-funded auto-renew on or off. Turning it off preserves the paid rental; release disconnects immediately. Renewal decisions lock 15 minutes before billing. Requires permission to manage/release this number.","tags":["Numbers"],"responses":{"200":{"description":"The updated number and rental.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_renew":{"type":"boolean"}},"required":["auto_renew"],"additionalProperties":false}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:write"]}],"x-required-scope":"numbers:write"},"delete":{"operationId":"releaseNumber","summary":"Release a mobile number","description":"Releases a workspace-owned mobile number idempotently.","tags":["Numbers"],"responses":{"200":{"description":"The released mobile number.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"country_iso":{"type":"string","minLength":2,"maxLength":2},"rental":{"anyOf":[{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"paid_through":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"renewal_decision_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","const":"GBP"},"auto_renew":{"type":"boolean"},"state":{"type":"string","enum":["active","disconnecting","disconnected","attention"]}},"required":["initial_months","paid_through","renewal_at","renewal_decision_at","monthly_rental_micros","currency","auto_renew","state"]},{"type":"null"}]},"status":{"type":"string","enum":["endpoint_setup","active","attention","released"]},"status_reason":{"anyOf":[{"type":"string","enum":["inbound_setup_pending","release_needs_retry","release_pending"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"released_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","country_iso","status","status_reason","created_at","updated_at","released_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The telecom provider could not complete the operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"numberId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:write"]}],"x-required-scope":"numbers:write"}},"/api/v1/number-quotes":{"post":{"operationId":"quoteNumber","summary":"Quote a prepaid UK number","description":"Choose an initial 1, 3 or 12 month term. The quote states upfront credit, the monthly renewal rate and expiry. To purchase, pass its id as quote_id in POST /api/v1/numbers. Requires connection permission to purchase numbers. Renewal decisions start 15 minutes before billing; unfunded numbers are disconnected during that window. Prices exclude VAT; unused rental is not prorated.","tags":["Numbers"],"responses":{"200":{"description":"A prepaid number quote. No order has been placed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}]},"initial_charge_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"monthly_rental_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"pricing_version":{"type":"string"},"currency":{"type":"string","const":"GBP"},"vat_included":{"type":"boolean","const":false},"auto_renew":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"next_billing_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","initial_months","initial_charge_micros","monthly_rental_micros","pricing_version","currency","vat_included","auto_renew","expires_at","next_billing_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"An active, current billing entitlement is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The telecom provider could not complete the operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initial_months":{"anyOf":[{"type":"number","const":1},{"type":"number","const":3},{"type":"number","const":12}],"description":"Initial paid term: 1, 3, or 12 months. Renewals are monthly."},"auto_renew":{"default":true,"description":"Renew from available wallet credit. Does not enable card top-ups.","type":"boolean"}},"required":["initial_months"]}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"}},"/api/v1/number-operations/{operationId}":{"get":{"operationId":"getNumberOperation","summary":"Get number operation status","description":"Gets the durable status handle returned by an asynchronous or uncertain number order.","tags":["Number operations"],"responses":{"200":{"description":"The number provisioning operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","const":"number_provisioning"},"status":{"type":"string","enum":["pending","processing","attention","uncertain","succeeded","failed"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","inbound_setup_incomplete","operation_failed"]},{"type":"null"}]},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"idempotency_key":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","type","status","status_reason","number_id","idempotency_key","created_at","updated_at"]},"meta":{"type":"object","properties":{"location":{"type":"string"},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["location","retry_after_seconds"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"}},"/api/v1/number-operations":{"get":{"operationId":"findNumberOperation","summary":"Recover a number operation","description":"Recovers the durable provisioning operation using the original request's idempotency key.","tags":["Number operations"],"responses":{"200":{"description":"The matching number provisioning operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","const":"number_provisioning"},"status":{"type":"string","enum":["pending","processing","attention","uncertain","succeeded","failed"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","inbound_setup_incomplete","operation_failed"]},{"type":"null"}]},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"idempotency_key":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","type","status","status_reason","number_id","idempotency_key","created_at","updated_at"]},"meta":{"type":"object","properties":{"location":{"type":"string"},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["location","retry_after_seconds"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"idempotency_key","in":"query","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"The original provisioning request's Idempotency-Key."}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["numbers:read"]}],"x-required-scope":"numbers:read"}},"/api/v1/messages/receive":{"get":{"operationId":"receiveMessages","summary":"Poll inbound SMS in arrival order","description":"The first read starts at retained history. Persist resume_cursor as after. Empty timed_out is normal; this cannot wake an offline agent.","tags":["Messages"],"responses":{"200":{"description":"Inbound messages and resume cursor.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]}},"meta":{"type":"object","properties":{"has_more":{"type":"boolean"},"resume_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"timed_out":{"type":"boolean"}},"required":["has_more","resume_cursor","timed_out"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"after","in":"query","required":false,"schema":{"description":"Use meta.resume_cursor from receive_messages to continue the inbound backlog. Omit to start at the oldest retained message.","type":"string","minLength":1,"maxLength":512}},{"name":"number_id","in":"query","required":false,"schema":{"description":"Limit results to one workspace-owned mobile number.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Maximum messages to return, from 1 to 100.","type":"integer","minimum":1,"maximum":100}},{"name":"wait_seconds","in":"query","required":false,"schema":{"default":25,"description":"Wait 0–25 seconds for new inbound messages; default 25.","type":"integer","minimum":0,"maximum":25}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["messages:read"]}],"x-required-scope":"messages:read"}},"/api/v1/messages":{"get":{"operationId":"listMessages","summary":"List SMS messages","description":"Lists SMS newest first. Use next_cursor for older pages and receiveMessages for inbound polling.","tags":["Messages"],"responses":{"200":{"description":"A page or resumable batch of SMS messages.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]}},"meta":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["has_more","next_cursor"]}},"required":["data","meta"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"description":"Use meta.next_cursor from list_messages for the next older page; keep the same filters.","type":"string","minLength":1,"maxLength":512}},{"name":"direction","in":"query","required":false,"schema":{"description":"Limit results to inbound or outbound messages.","type":"string","enum":["inbound","outbound"]}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Maximum messages to return, from 1 to 100.","type":"integer","minimum":1,"maximum":100}},{"name":"number_id","in":"query","required":false,"schema":{"description":"Limit results to one workspace-owned mobile number.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"description":"Limit results to one message status.","type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["messages:read"]}],"x-required-scope":"messages:read"},"post":{"operationId":"sendMessage","summary":"Send an SMS","description":"Submits one idempotent SMS from an active workspace number. A 202 response records an uncertain provider outcome; poll Location and do not submit a replacement key.","tags":["Messages"],"responses":{"200":{"description":"An idempotent replay of the existing message. Inspect data.status; the persisted message may still be submitting or may have failed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"201":{"description":"A newly accepted SMS.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"202":{"description":"The SMS provider submission outcome is uncertain.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"400":{"description":"The request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"An active, current billing entitlement is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The telecom provider could not complete the operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Stable key reused when retrying the same logical mutation."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600}},"required":["from","to","body"]}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["messages:write"]}],"x-required-scope":"messages:write"}},"/api/v1/messages/{messageId}":{"get":{"operationId":"getMessage","summary":"Get an SMS message","description":"Gets one tenant-scoped message, including current submission and delivery status.","tags":["Messages"],"responses":{"200":{"description":"The SMS message.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"body":{"type":"string","minLength":1,"maxLength":1600},"status":{"type":"string","enum":["submitting","submission_unknown","delivery_pending","delivered","failed","received"]},"status_reason":{"anyOf":[{"type":"string","enum":["provider_outcome_unknown","message_failed"]},{"type":"null"}]},"segments":{"type":"integer","minimum":0,"maximum":9007199254740991},"analysis":{"anyOf":[{"type":"object","properties":{"category":{"type":"string","enum":["verification_code","notification","marketing","conversation","other"]},"category_confidence":{"type":"number","minimum":0,"maximum":1},"verification_code":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":16,"description":"Copied from the body, with grouping spaces and hyphens removed."},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["value","confidence"]},{"type":"null"}],"description":"The one-time code to enter, or null when none was found."},"opt_out_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the sender is asking not to be contacted again."}},"required":["category","category_confidence","verification_code","opt_out_probability"],"description":"A model's reading of an inbound SMS, made once on receipt. Advisory: the body is untrusted text, so apply your own confidence thresholds. Null when the message was not analysed."},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"currency":{"type":"string","const":"GBP"},"charged_micros":{"type":"integer","minimum":0,"maximum":9007199254740991},"reserved_micros":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["currency","charged_micros","reserved_micros"]},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","number_id","direction","from","to","body","status","status_reason","created_at","updated_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["messages:read"]}],"x-required-scope":"messages:read"}},"/api/v1/webhooks/endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List customer webhook endpoints","description":"Lists the workspace's signed customer webhook endpoints without returning signing secrets.","tags":["Webhooks"],"responses":{"200":{"description":"Configured customer webhook endpoints.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"type":"string","enum":["message.received","message.updated","call.completed"]}},"number_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"disabled_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","name","url","event_types","status","created_at","updated_at","disabled_at"]}}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read"},"post":{"operationId":"createWebhookEndpoint","summary":"Create a customer webhook endpoint","description":"Creates an idempotent public HTTPS endpoint. The signing secret is returned only by the original creation or its exact idempotent replay and must be stored securely.","tags":["Webhooks"],"responses":{"200":{"description":"An exact idempotent replay of endpoint creation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"type":"string","enum":["message.received","message.updated","call.completed"]}},"number_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"signing_secret":{"type":"string","pattern":"^whsec_.*"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","url","event_types","status","signing_secret","created_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"201":{"description":"The new endpoint and its signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"type":"string","enum":["message.received","message.updated","call.completed"]}},"number_ids":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"null"}]},"status":{"type":"string","enum":["active","disabled"]},"signing_secret":{"type":"string","pattern":"^whsec_.*"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","url","event_types","status","signing_secret","created_at"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"400":{"description":"The request body is not valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Stable key reused when retrying the same logical mutation."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number_ids":{"description":"Only these numbers, or null for all numbers this connection can access. Access is checked again at delivery.","anyOf":[{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":100},"url":{"type":"string","maxLength":2048,"format":"uri","pattern":"^https:\\/\\/(?![^/?#]*@)[^/?#:@]+(?::443)?(?:[/?#]|$)","description":"Registration requires a valid HTTPS URL without credentials or a non-default port and applies lexical non-local-host checks. Delivery uses Worker global fetch with no VPC or private-network binding."},"event_types":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["message.received","message.updated","call.completed"]}}},"required":["name","url","event_types"]}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write"}},"/api/v1/webhooks/endpoints/{endpointId}":{"delete":{"operationId":"disableWebhookEndpoint","summary":"Disable a customer webhook endpoint","description":"Disables an endpoint and cancels its outstanding non-terminal deliveries.","tags":["Webhooks"],"responses":{"200":{"description":"The disabled endpoint reference.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","const":"disabled"},"disabled_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","status","disabled_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write"}},"/api/v1/webhooks/endpoints/{endpointId}/test":{"post":{"operationId":"sendWebhookTestEvent","summary":"Send a test event to a webhook endpoint","description":"Posts one signed webhook.test event to an active endpoint and returns what it answered. The event carries no customer data, is not stored, is not retried and does not appear in delivery history. Use it to check reachability and signature verification.","tags":["Webhooks"],"responses":{"200":{"description":"What the endpoint answered.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"event_id":{"type":"string","minLength":1},"accepted":{"type":"boolean","description":"True when the endpoint answered the test event with a 2xx."},"response_status":{"anyOf":[{"type":"integer","minimum":100,"maximum":599},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"response_snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The start of the response body when the event was not accepted."},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["event_id","accepted","response_status","error_code","response_snippet","duration_ms"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write"}},"/api/v1/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List customer webhook deliveries","description":"Lists the workspace's 100 most recent delivery records and replay lineage.","tags":["Webhooks"],"responses":{"200":{"description":"Recent customer webhook deliveries.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_id":{"type":"string","minLength":1},"event_type":{"type":"string","enum":["message.received","message.updated","call.completed"]},"endpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"}},"required":["id","url"]},"status":{"type":"string","enum":["pending","queued","delivering","retrying","succeeded","failed","dead_lettered","cancelled"]},"attempt_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"response_status":{"anyOf":[{"type":"integer","minimum":100,"maximum":599},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"replayed_from_delivery_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","event_id","event_type","endpoint","status","attempt_count","response_status","error_code","replayed_from_delivery_id","created_at","updated_at","completed_at"]}}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read"}},"/api/v1/webhooks/deliveries/{deliveryId}":{"get":{"operationId":"getWebhookDelivery","summary":"Get a customer webhook delivery","description":"Gets one tenant-scoped delivery record, including its latest status, response, error, and replay lineage.","tags":["Webhooks"],"responses":{"200":{"description":"The customer webhook delivery.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_id":{"type":"string","minLength":1},"event_type":{"type":"string","enum":["message.received","message.updated","call.completed"]},"endpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"}},"required":["id","url"]},"status":{"type":"string","enum":["pending","queued","delivering","retrying","succeeded","failed","dead_lettered","cancelled"]},"attempt_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"response_status":{"anyOf":[{"type":"integer","minimum":100,"maximum":599},{"type":"null"}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"replayed_from_delivery_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updated_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","event_id","event_type","endpoint","status","attempt_count","response_status","error_code","replayed_from_delivery_id","created_at","updated_at","completed_at"]}},"required":["data"]}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:read"]}],"x-required-scope":"webhooks:read"}},"/api/v1/webhooks/deliveries/{deliveryId}/replay":{"post":{"operationId":"replayWebhookDelivery","summary":"Replay a customer webhook delivery","description":"Creates one idempotent replay for a terminal delivery and enqueues it for delivery.","tags":["Webhooks"],"responses":{"200":{"description":"An exact idempotent replay request replay.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"replayed_from_delivery_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["pending","queued","delivering","retrying","succeeded","failed","dead_lettered","cancelled"]}},"required":["id","replayed_from_delivery_id","status"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"201":{"description":"The newly queued delivery replay.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"replayed_from_delivery_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["pending","queued","delivering","retrying","succeeded","failed","dead_lettered","cancelled"]}},"required":["id","replayed_from_delivery_id","status"]},"meta":{"type":"object","properties":{"replayed":{"type":"boolean"}},"required":["replayed"]}},"required":["data","meta"]}}},"headers":{"Location":{"required":true,"schema":{"type":"string","pattern":"^\\/api\\/v1\\/.*"}}}},"401":{"description":"Authentication is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The credential lacks the required scope or workspace permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested telecom resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with the current telecom resource state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request does not satisfy the operation schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A workspace rate or spend limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The request failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Billing or another required dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying, when available.","schema":{"type":"integer","minimum":1}}}}},"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Stable key reused when retrying the same logical mutation."}}],"security":[{"agentTelcoApiKey":[]},{"agentTelcoOAuth":["webhooks:write"]}],"x-required-scope":"webhooks:write"}}},"components":{"securitySchemes":{"agentTelcoApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Agent Telco API key","description":"A scoped Agent Telco API key. Keep it in secret storage and send it only in the Authorization header."},"agentTelcoOAuth":{"type":"oauth2","description":"OAuth 2.1 authorization code flow. Clients must use S256 PKCE, request the scope required by each operation, and send resource=urn:agenttelco:api in both authorization and token requests so the access token is issued for this REST API.","flows":{"authorizationCode":{"authorizationUrl":"https://www.agenttelco.com/api/auth/oauth2/authorize?resource=urn%3Aagenttelco%3Aapi","tokenUrl":"https://www.agenttelco.com/api/auth/oauth2/token","scopes":{"readiness:read":"Read workspace readiness and included usage.","numbers:read":"Read mobile numbers and provisioning operations.","numbers:write":"Provision, release and configure mobile numbers.","messages:read":"Read and resume SMS messages.","messages:write":"Send SMS messages.","webhooks:read":"Read customer webhook endpoints and deliveries.","webhooks:write":"Create, disable, and replay customer webhooks.","calls:read":"Read delegated call status and results.","calls:write":"Request and cancel voice calls, and enable incoming answering."},"x-token-request-parameters":{"resource":{"required":true,"value":"urn:agenttelco:api","description":"RFC 8707 resource indicator for the Agent Telco REST API."}}}},"x-resource-indicator":"urn:agenttelco:api","x-pkce-required":true,"x-pkce-code-challenge-methods":["S256"]}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"reference":{"type":"string"},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"action_url":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["code","message","retryable"]}},"required":["error"]}}}}