{"openapi":"3.1.0","info":{"title":"Agent Telco API","version":"1.0.0","description":"A REST API for agents to provision mobile numbers and exchange SMS messages."},"servers":[{"url":"https://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/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/readiness":{"get":{"operationId":"getReadiness","summary":"Get workspace readiness","description":"Returns account gates, capability-specific blockers, and current included usage before an agent attempts telecom mutations.","tags":["Readiness"],"responses":{"200":{"description":"Current workspace readiness and usage.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["account_suspended","billing_inactive","billing_past_due","mobile_identity_limit_reached","provider_mutations_disabled","sms_capacity_exhausted"]},"message":{"type":"string","minLength":1}},"required":["code","message"]}},"capabilities":{"type":"object","properties":{"provision_mobile_identity":{"type":"object","properties":{"ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string","enum":["account_suspended","billing_inactive","billing_past_due","mobile_identity_limit_reached","provider_mutations_disabled","sms_capacity_exhausted"]}}},"required":["ready","blockers"]},"send_sms":{"type":"object","properties":{"ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string","enum":["account_suspended","billing_inactive","billing_past_due","mobile_identity_limit_reached","provider_mutations_disabled","sms_capacity_exhausted"]}}},"required":["ready","blockers"]}},"required":["provision_mobile_identity","send_sms"]},"account":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended"]},"billing_status":{"type":"string","enum":["inactive","active","past_due"]},"plan":{"type":"string","minLength":1}},"required":["status","billing_status","plan"]},"usage":{"type":"object","properties":{"period":{"type":"string","minLength":1},"mobile_identities":{"type":"object","properties":{"used":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["used","limit","remaining"]},"sms_segments":{"type":"object","properties":{"used":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["used","limit","remaining"]},"api_requests_per_minute":{"type":"object","properties":{"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["limit"]}},"required":["period","mobile_identities","sms_segments","api_requests_per_minute"]}},"required":["ready","blockers","capabilities","account","usage"]}},"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},"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":"Starts one idempotent number order. Reuse the same Idempotency-Key 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},"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},"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"]}},"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}}}}},"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."}}],"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},"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"},"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},"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-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"]}},"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"]}},"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":{"get":{"operationId":"listMessages","summary":"List SMS messages","description":"Lists SMS with stable historical pagination. Persist meta.resume_cursor and send it as after for resumable forward reads; wait_seconds can long-poll an empty forward read. after and cursor are mutually exclusive.","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)$"},"phone_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"}]},"provider_message_sid":{"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|([+-](?:[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","phone_number_id","direction","from","to","body","status","status_reason","provider_message_sid","created_at","updated_at"]}},"meta":{"type":"object","properties":{"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"resume_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"timed_out":{"type":"boolean"}},"required":["has_more","next_cursor","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"}}}},"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":"after","in":"query","required":false,"schema":{"description":"Resume cursor returned by an earlier message list response. Cannot be combined with cursor.","type":"string","minLength":1,"maxLength":512}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Pagination cursor for the next older page. Cannot be combined with after.","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"]}},{"name":"wait_seconds","in":"query","required":false,"schema":{"default":0,"description":"Long-poll an empty forward read for up to 25 seconds.","type":"integer","minimum":0,"maximum":25}}],"x-mutually-exclusive-query-parameters":[["after","cursor"]],"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)$"},"phone_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"}]},"provider_message_sid":{"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|([+-](?:[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","phone_number_id","direction","from","to","body","status","status_reason","provider_message_sid","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)$"},"phone_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"}]},"provider_message_sid":{"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|([+-](?:[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","phone_number_id","direction","from","to","body","status","status_reason","provider_message_sid","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)$"},"phone_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"}]},"provider_message_sid":{"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|([+-](?:[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","phone_number_id","direction","from","to","body","status","status_reason","provider_message_sid","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)$"},"phone_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"}]},"provider_message_sid":{"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|([+-](?:[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","phone_number_id","direction","from","to","body","status","status_reason","provider_message_sid","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"]}},"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"]}},"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"]}},"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":{"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":2,"type":"array","items":{"type":"string","enum":["message.received","message.updated"]}}},"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/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"]},"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"]},"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://agenttelco.com/api/auth/oauth2/authorize?resource=urn%3Aagenttelco%3Aapi","tokenUrl":"https://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 and release 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."},"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"}},"required":["code","message"]}},"required":["error"]}}}}