{ "openapi": "3.1.0", "info": { "title": "sipsandwich API", "version": "0.1.0", "description": "Tenant API for SIP trunking, Retell AI routing, phone number workflows, and telemetry." }, "servers": [ { "url": "https://api.sipsandwich.ai", "description": "Production tenant API" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/phone-numbers": { "get": { "summary": "List phone numbers and SIP users", "responses": { "200": { "description": "Phone numbers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Phone Numbers" ] }, "post": { "summary": "Create a phone number or SIP user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "responses": { "201": { "description": "Created phone number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Phone Numbers" ] } }, "/api/v1/phone-numbers/{id}": { "get": { "summary": "Get phone number details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Phone number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Phone Numbers" ] }, "patch": { "summary": "Update a phone number or SIP user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPolicy" } } } }, "responses": { "200": { "description": "Updated phone number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Phone Numbers" ] }, "delete": { "summary": "Delete a phone number", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted." } }, "security": [ { "bearerAuth": [] } ], "tags": [ "Phone Numbers" ] } }, "/api/v1/calls": { "get": { "summary": "List SIP telemetry and call history", "responses": { "200": { "description": "Call telemetry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/SipCall" } } } } } } } }, "tags": [ "Telemetry" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } } ], "security": [ { "bearerAuth": [] } ] } }, "/api/v1/retell/connect-token": { "post": { "tags": [ "Retell" ], "summary": "Connect or rotate the tenant Retell API token and sync agents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetellTokenConnectRequest" } } } }, "responses": { "200": { "description": "Retell token connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "tokenLast4": { "type": "string" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/RetellAgent" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/retell/validate-token": { "post": { "tags": [ "Retell" ], "summary": "Validate a provided or stored Retell token", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetellValidateTokenRequest" } } } }, "responses": { "200": { "description": "Retell token is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "agentCount": { "type": "integer" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/retell/agents": { "get": { "tags": [ "Retell" ], "summary": "List cached Retell agents for assignment", "responses": { "200": { "description": "Retell agents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/RetellAgent" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/retell/agents/sync": { "post": { "tags": [ "Retell" ], "summary": "Sync Retell agents from the stored tenant token", "responses": { "200": { "description": "Retell agents synced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/RetellAgent" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/retell/phone-numbers": { "get": { "tags": [ "Retell" ], "summary": "List Retell provisioning view for tenant numbers", "responses": { "200": { "description": "Retell phone-number provisioning view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks": { "get": { "tags": [ "SIP Trunks" ], "summary": "List SIP provider trunks", "responses": { "200": { "description": "SIP trunks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunks": { "type": "array", "items": { "$ref": "#/components/schemas/SipTrunk" } }, "edge": { "$ref": "#/components/schemas/SipEdge" }, "inbound": { "$ref": "#/components/schemas/SipInboundTermination" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "SIP Trunks" ], "summary": "Create a SIP provider trunk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SipTrunkCreateRequest" } } } }, "responses": { "200": { "description": "Matching SIP provider reused and its registration projection refreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunk": { "$ref": "#/components/schemas/SipTrunk" }, "reused": { "type": "boolean", "const": true } } } } } }, "201": { "description": "SIP trunk created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunk": { "$ref": "#/components/schemas/SipTrunk" }, "reused": { "type": "boolean", "const": false } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks/{id}": { "get": { "tags": [ "SIP Trunks" ], "summary": "Get SIP trunk details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SIP trunk.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunk": { "$ref": "#/components/schemas/SipTrunk" }, "inbound": { "$ref": "#/components/schemas/SipInboundTermination" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "SIP Trunks" ], "summary": "Update SIP trunk settings or rotate provider password", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SipTrunkPatchRequest" } } } }, "responses": { "200": { "description": "SIP trunk updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunk": { "$ref": "#/components/schemas/SipTrunk" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "SIP Trunks" ], "summary": "Delete a SIP provider trunk", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SIP trunk deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks/{id}/status": { "get": { "tags": [ "SIP Trunks" ], "summary": "Get live SIP registration status for a trunk", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SIP registration status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "lastCode": { "type": [ "integer", "null" ] }, "lastReason": { "type": [ "string", "null" ] }, "registrant": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks/{id}/register/reload": { "post": { "tags": [ "SIP Trunks" ], "summary": "Reload SIP registration for a trunk", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reload requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks/{id}/register/force": { "post": { "tags": [ "SIP Trunks" ], "summary": "Force registration attempt for a trunk", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Force registration requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/sip/trunks/{id}/registration-events": { "get": { "tags": [ "SIP Trunks" ], "summary": "List SIP registration events for a trunk", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Registration events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/SipRegistrationEvent" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/phone-numbers/{id}/provision-retell": { "post": { "tags": [ "Phone Numbers" ], "summary": "Queue Retell import/provisioning for a phone number or SIP user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retell provisioning queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/phone-numbers/{id}/sync-retell": { "post": { "tags": [ "Phone Numbers" ], "summary": "Queue Retell update/sync for a phone number or SIP user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retell sync queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/phone-numbers/{id}/rotate-retell-auth": { "post": { "tags": [ "Phone Numbers" ], "summary": "Rotate Retell-facing SIP digest credentials", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rotateUsername": { "type": "boolean", "default": false, "description": "Defaults to false. When false, only the Retell-facing SIP password is rotated and the existing username is preserved." } } } } } }, "responses": { "200": { "description": "Retell-facing SIP auth rotated and Retell update queued when a Retell token is connected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "$ref": "#/components/schemas/PhoneNumber" }, "job": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "queue": { "type": "string", "example": "retell.updatePhoneNumber" }, "status": { "type": "string", "example": "queued" } } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/phone-numbers/{id}/retell/create-call": { "post": { "tags": [ "Phone Numbers" ], "summary": "Place an outbound Retell call from this number", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetellCallRequest" } } } }, "responses": { "200": { "description": "Retell outbound call created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRetellCallResponse" } } } }, "400": { "description": "Invalid request or number not ready for outbound calls." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/calls/{id}": { "get": { "tags": [ "Telemetry" ], "summary": "Get call detail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Call detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "$ref": "#/components/schemas/SipCall" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/calls/{id}/sip-flow": { "get": { "tags": [ "Telemetry" ], "summary": "Get simplified SIP ladder events for a call", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SIP flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SipFlow" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/calls/{id}/sipsandwich-pcap": { "get": { "tags": [ "Telemetry" ], "summary": "Download sipsandwich SIP PCAP for a call", "description": "Returns an authenticated signaling-only PCAP attachment built from captured SIP messages. This endpoint is the canonical call-log PCAP download path and does not send users to the Homer UI.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generated sipsandwich SIP PCAP attachment.", "headers": { "content-disposition": { "description": "Attachment filename for the generated PCAP.", "schema": { "type": "string" } } }, "content": { "application/vnd.tcpdump.pcap": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found or no captured SIP messages were available." }, "503": { "description": "sipsandwich PCAP capture API is not configured." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/calls/{id}/homer-pcap": { "get": { "tags": [ "Telemetry" ], "summary": "Download sipsandwich SIP PCAP for a call (compatibility alias)", "description": "Compatibility alias for older clients. New integrations should use /api/v1/calls/{id}/sipsandwich-pcap.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generated sipsandwich SIP PCAP attachment.", "headers": { "content-disposition": { "description": "Attachment filename for the generated PCAP.", "schema": { "type": "string" } } }, "content": { "application/vnd.tcpdump.pcap": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found or no captured SIP messages were available." }, "503": { "description": "sipsandwich PCAP capture API is not configured." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions": { "get": { "tags": [ "Telemetry" ], "summary": "List SIP trace sessions", "responses": { "200": { "description": "Trace sessions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceSessions": { "type": "array", "items": { "$ref": "#/components/schemas/TraceSession" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Telemetry" ], "summary": "Start a SIP trace session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceSessionCreateRequest" } } } }, "responses": { "201": { "description": "Trace session started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceSession": { "$ref": "#/components/schemas/TraceSession" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions/{id}/stop": { "patch": { "tags": [ "Telemetry" ], "summary": "Stop a SIP trace session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Trace session stopped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceSession": { "$ref": "#/components/schemas/TraceSession" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions/{id}": { "delete": { "tags": [ "Telemetry" ], "summary": "Delete a SIP trace session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Trace session deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions/{id}/homer-link": { "get": { "tags": [ "Telemetry" ], "summary": "Get Homer link for a SIP trace session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Homer link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions/{id}/sipsandwich-pcap": { "get": { "tags": [ "Telemetry" ], "summary": "Download a sipsandwich PCAP for a SIP trace session", "description": "Returns an authenticated signaling-only PCAP attachment built from captured SIP messages for a trace session with a Call-ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PCAP attachment.", "content": { "application/vnd.tcpdump.pcap": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Trace session cannot be exported as a PCAP." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." }, "503": { "description": "sipsandwich PCAP capture API is not configured." } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/trace-sessions/{id}/homer-events": { "get": { "tags": [ "Telemetry" ], "summary": "Fetch Homer SIP events for a trace session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "Homer SIP events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "callId": { "type": "string" }, "configured": { "type": "boolean" }, "total": { "type": "integer" }, "warning": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/HomerTraceEvent" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Insufficient permissions." }, "404": { "description": "Resource not found." }, "502": { "description": "Homer API request failed." } }, "security": [ { "bearerAuth": [] } ] } } }, "tags": [ { "name": "Retell", "description": "Connect Retell, validate credentials, and synchronize agents." }, { "name": "SIP Trunks", "description": "Configure SIP providers and operate registration state." }, { "name": "Phone Numbers", "description": "Manage tenant numbers, Retell provisioning, and outbound calls." }, { "name": "Telemetry", "description": "Inspect calls and run bounded SIP trace sessions." } ], "components": { "schemas": { "PhoneNumber": { "allOf": [ { "$ref": "#/components/schemas/RoutingPolicy" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "trunkId": { "type": "string", "format": "uuid" }, "e164": { "type": "string", "description": "Phone number or SIP user imported to Retell." }, "providerAliases": { "type": "array", "items": { "type": "string" } }, "retellImportIdentifier": { "type": "string" }, "routingMode": { "type": "string", "enum": [ "imported_number", "dial_to_sip" ] }, "enabled": { "type": "boolean" }, "inboundEnabled": { "type": "boolean" }, "outboundEnabled": { "type": "boolean" }, "pstnFailoverEnabled": { "type": "boolean" }, "pstnFailoverDestination": { "type": [ "string", "null" ], "description": "Verified US PSTN failover forwarding destination." }, "pstnFailoverVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pstnFailoverVerificationStatus": { "type": "string", "enum": [ "not_configured", "pending", "verified", "failed", "expired" ] }, "sipHeaderMappings": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SipHeaderMapping" } }, "retellWorkspaceAssignments": { "type": "array", "description": "Additional Retell workspace imports and agent assignments for this number.", "items": { "$ref": "#/components/schemas/PhoneNumberRetellWorkspace" } } } } ] }, "RoutingPolicy": { "type": "object", "properties": { "retellConcurrencyCheckEnabled": { "type": "boolean" }, "retellConcurrencyBurstAllowed": { "type": "boolean" }, "failoverEnabled": { "type": "boolean" }, "failoverDestination": { "type": [ "string", "null" ], "examples": [ "+15551234567@carrier.example.com" ], "description": "Generic SIP failover destination. The sip: or sips: prefix is optional; the API normalizes before routing." }, "businessHoursEnabled": { "type": "boolean" }, "businessHoursTimezone": { "type": "string", "examples": [ "America/New_York" ] }, "businessHoursSchedule": { "type": "array", "items": { "type": "object", "required": [ "days", "start", "end" ], "properties": { "days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "0=Sunday, 6=Saturday." }, "start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "action": { "type": "string", "enum": [ "retell", "failover" ], "description": "Per-window routing action. failover uses destination when provided, otherwise the default outside-hours route." }, "destination": { "type": [ "string", "null" ], "description": "Optional per-window SIP destination override. The sip: or sips: prefix is optional.", "examples": [ "afterhours@carrier.example.com" ] } } } }, "businessHoursRouteMode": { "type": "string", "enum": [ "retell_open", "retell_closed" ] }, "businessHoursOutsideDestination": { "type": [ "string", "null" ], "description": "Default outside-hours SIP destination when businessHoursOutsideDestinationMode is sip_uri. The sip: or sips: prefix is optional.", "examples": [ "afterhours@carrier.example.com" ] }, "inboundRetellHeaders": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^X-[A-Za-z0-9-]+$" }, "value": { "type": "string" } } } }, "inboundWebhookUrl": { "type": [ "string", "null" ], "format": "uri" }, "inboundWebhookAuthType": { "type": "string", "enum": [ "none", "bearer", "basic", "hmac_sha256" ] }, "inboundWebhookAuthSecret": { "type": "string", "writeOnly": true }, "inboundWebhookSigningSecret": { "type": "string", "writeOnly": true }, "callerIdLookupWebhookEnabled": { "type": "boolean", "default": false }, "callerIdLookupWebhookUrl": { "type": [ "string", "null" ], "format": "uri" }, "callerIdLookupWebhookAuthType": { "type": "string", "enum": [ "none", "bearer", "basic", "hmac_sha256" ] }, "callerIdLookupWebhookAuthSecret": { "type": "string", "writeOnly": true }, "callerIdLookupWebhookSigningSecret": { "type": "string", "writeOnly": true }, "callerIdLookupWebhookTimeoutMs": { "type": "integer", "minimum": 250, "maximum": 5000, "default": 1000 }, "callerIdLookupWebhookFailureMode": { "type": "string", "enum": [ "allow", "block", "failover" ], "default": "allow" }, "failoverDestinationMode": { "type": "string", "enum": [ "sip_uri", "extension" ], "default": "sip_uri", "description": "sip_uri routes to a full SIP/SIPS URI. extension builds a SIP URI against the existing provider connection." }, "failoverExtension": { "type": [ "string", "null" ], "description": "User, extension, DID, or SIP username to route over the existing provider connection when failoverDestinationMode is extension.", "examples": [ "1001", "+15551234567" ] }, "failoverTransport": { "type": [ "string", "null" ], "enum": [ "TCP", "UDP", "TLS", null ], "description": "Optional transport override for generic SIP failover. Blank uses the SIP URI or provider transport." }, "businessHoursOutsideDestinationMode": { "type": "string", "enum": [ "sip_connection", "sip_uri", "pstn_failover" ], "default": "sip_connection", "description": "Default outside-hours route: existing SIP provider connection, explicit SIP URI, or verified managed PSTN failover." }, "businessHoursOutsideExtension": { "type": [ "string", "null" ], "description": "User, extension, DID, or SIP username to route over the existing SIP provider connection for outside-hours calls.", "examples": [ "1001", "+15551234567" ] }, "businessHoursOutsideTransport": { "type": [ "string", "null" ], "enum": [ "TCP", "UDP", "TLS", null ], "description": "Optional transport override for the outside-hours SIP destination. Blank uses the provider or URI default." } } }, "SipCall": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "callId": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "state": { "type": "string" }, "fromUser": { "type": [ "string", "null" ] }, "toUser": { "type": [ "string", "null" ] }, "sourceIp": { "type": [ "string", "null" ] }, "finalResponseCode": { "type": [ "integer", "null" ] }, "finalResponseReason": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sipsandwichPcapUrl": { "type": "string", "description": "Canonical authenticated app API endpoint for downloading this call as a sipsandwich SIP PCAP." }, "homerLink": { "type": "string", "description": "Backward-compatible call-log PCAP download URL." }, "homerPcapUrl": { "type": "string", "description": "Backward-compatible alias of sipsandwichPcapUrl for older web bundles." } } }, "RetellTokenConnectRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 8, "writeOnly": true } } }, "RetellAgent": { "type": "object", "properties": { "id": { "type": "string" }, "cacheId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": [ "integer", "null" ] }, "baseVersion": { "type": [ "integer", "null" ] }, "versionTitle": { "type": [ "string", "null" ] }, "versionDescription": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "published": { "type": [ "boolean", "null" ] }, "fetchedAt": { "type": "string", "format": "date-time" } } }, "RetellValidateTokenRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "writeOnly": true, "description": "Optional. If omitted, validates the stored tenant Retell token." } } }, "SipTrunk": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "registrarUri": { "type": "string", "example": "sip:sip.provider.example", "description": "Provider registration target, or the outbound SIP destination when authenticationMode is ip." }, "proxyUri": { "type": [ "string", "null" ] }, "outboundProxyUri": { "type": [ "string", "null" ] }, "transport": { "type": "string", "enum": [ "udp", "tcp", "tls" ] }, "authenticationMode": { "type": "string", "enum": [ "registration", "digest", "ip" ] }, "username": { "type": "string" }, "authUsername": { "type": "string" }, "providerProfile": { "type": "string", "enum": [ "default", "telnyx_like", "voipms_like", "bandwidth_like", "custom" ] }, "fromDomain": { "type": [ "string", "null" ] }, "fromUserMode": { "type": "string", "enum": [ "e164", "auth_username", "custom" ] }, "customFromUser": { "type": [ "string", "null" ] }, "expiresSeconds": { "type": "integer" }, "providerSourceIps": { "type": "array", "description": "Explicit inbound carrier source IPs or CIDRs trusted by IP authentication. These are separate from registrarUri, the outbound destination.", "items": { "type": "string" } }, "customHeaders": { "type": "array", "items": { "$ref": "#/components/schemas/SipCustomHeader" } }, "enabled": { "type": "boolean" }, "registrationStatus": { "type": "string" }, "registrationLastCode": { "type": [ "integer", "null" ] }, "registrationLastReason": { "type": [ "string", "null" ] }, "contactUsername": { "type": "string" }, "contactUri": { "type": [ "string", "null" ] }, "forcedSocket": { "type": [ "string", "null" ] }, "contactHostMode": { "type": "string", "enum": [ "sip_domain", "public_ip" ], "description": "Controls whether the OpenSIPS Contact header uses the tenant SIP domain or the edge public IP." }, "contactDomain": { "type": "string" }, "publicIp": { "type": [ "string", "null" ] }, "sipDomain": { "type": [ "string", "null" ] } } }, "SipEdge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "publicIp": { "type": "string", "example": "15.204.36.209" }, "sipDomain": { "type": "string", "example": "sip.sipsandwich.ai" } } }, "SipInboundTermination": { "type": "object", "required": [ "host", "uri", "ip", "sipPort", "tlsPort" ], "properties": { "host": { "type": "string", "description": "Tenant SIP hostname carriers should prefer for inbound delivery.", "example": "acme.sip.sipsandwich.ai" }, "uri": { "type": "string", "description": "Copyable inbound SIP termination URI.", "example": "sip:acme.sip.sipsandwich.ai" }, "ip": { "type": "string", "description": "IP fallback when the carrier cannot target a hostname.", "example": "15.204.36.209" }, "sipPort": { "type": "integer", "minimum": 1, "maximum": 65535, "example": 5060 }, "tlsPort": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535, "example": 5061 } } }, "SipTrunkCreateRequest": { "type": "object", "required": [ "label", "registrarUri", "transport", "username" ], "properties": { "label": { "type": "string" }, "registrarUri": { "type": "string", "example": "sip:sip.provider.example", "description": "Provider registrar SIP URI or host. For IP authentication, this is the outbound SIP destination. Include a non-standard port when needed, for example sip:registrar.example.com:5070." }, "proxyUri": { "type": "string" }, "outboundProxyUri": { "type": "string", "description": "Optional outbound SIP proxy used by the OpenSIPS registration projection." }, "transport": { "type": "string", "enum": [ "udp", "tcp", "tls" ] }, "authenticationMode": { "type": "string", "enum": [ "registration", "digest", "ip" ], "default": "registration", "description": "IP authentication requires providerSourceIps and no password. Registration and digest authentication require a password." }, "username": { "type": "string" }, "authUsername": { "type": "string", "description": "Optional SIP digest auth username. Defaults to username when omitted." }, "password": { "type": "string", "writeOnly": true, "description": "Required for registration and digest authentication. Omit for IP authentication." }, "providerProfile": { "type": "string", "enum": [ "default", "telnyx_like", "voipms_like", "bandwidth_like", "custom" ], "default": "default" }, "fromDomain": { "type": "string" }, "fromUserMode": { "type": "string", "enum": [ "e164", "auth_username", "custom" ], "default": "e164" }, "customFromUser": { "type": "string" }, "expiresSeconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 300 }, "providerSourceIps": { "type": "array", "description": "Inbound carrier source IPs or CIDRs required for IP authentication. They are not derived from the outbound registrarUri.", "items": { "type": "string" } }, "customHeaders": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/SipCustomHeader" } }, "contactHostMode": { "type": "string", "enum": [ "sip_domain", "public_ip" ], "default": "sip_domain", "description": "Use public_ip when the carrier rejects FQDN values in the REGISTER Contact header." } } }, "SipTrunkPatchRequest": { "allOf": [ { "$ref": "#/components/schemas/SipTrunkCreateRequest" }, { "type": "object", "properties": { "enabled": { "type": "boolean" } } } ], "description": "All fields are optional on PATCH. Include password only to rotate the stored provider secret." }, "SipRegistrationEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "sipCode": { "type": [ "integer", "null" ] }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreateRetellCallRequest": { "type": "object", "required": [ "toNumber" ], "properties": { "toNumber": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Destination: E.164, 10/11-digit US, PBX extension, queue name, or SIP URI." }, "overrideAgentId": { "type": "string", "description": "Retell agent to use instead of the number's default outbound agent." }, "overrideAgentVersion": { "type": [ "integer", "string" ], "description": "Optional agent version override." }, "retellLlmDynamicVariables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "String values injected into the agent prompt." }, "customSipHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "X-* SIP headers to include; platform correlation headers are added automatically." }, "tags": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/OutboundCallTag" }, "description": "Any Retell create-phone-call override as a dotted-path tag." }, "originalCallerId": { "type": "string", "description": "Original caller ID carried in X-Original_Caller_ID." }, "fromUser": { "type": "string", "description": "From-user override carried in X-sipsandwich_from_user." } } }, "CreateRetellCallResponse": { "type": "object", "required": [ "callId", "callStatus", "fromNumber", "toNumber", "callGroup" ], "properties": { "callId": { "type": "string" }, "agentId": { "type": "string" }, "callStatus": { "type": "string" }, "fromNumber": { "type": "string" }, "toNumber": { "type": "string" }, "callGroup": { "type": "string" } } }, "SipFlow": { "type": "object", "properties": { "callId": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "label": { "type": "string" }, "status": { "type": "string" } } } } } }, "TraceSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "tenant", "trunk", "number", "call" ] }, "trunkId": { "type": [ "string", "null" ], "format": "uuid" }, "phoneNumberId": { "type": [ "string", "null" ], "format": "uuid" }, "callId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "sipsandwichPcapUrl": { "type": "string", "description": "Authenticated PCAP download URL for this trace session." }, "homerLink": { "type": [ "string", "null" ], "format": "uri" } } }, "TraceSessionCreateRequest": { "type": "object", "required": [ "scope", "durationMinutes" ], "properties": { "scope": { "type": "string", "enum": [ "tenant", "trunk", "number", "call" ] }, "trunkId": { "type": "string", "format": "uuid" }, "phoneNumberId": { "type": "string", "format": "uuid" }, "callId": { "type": "string" }, "durationMinutes": { "type": "integer", "enum": [ 5, 15, 30 ] }, "reason": { "type": "string" } } }, "HomerTraceEvent": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "type": "string" }, "method": { "type": [ "string", "null" ] }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "sourceIp": { "type": [ "string", "null" ] }, "sourcePort": { "type": [ "integer", "null" ] }, "destinationIp": { "type": [ "string", "null" ] }, "destinationPort": { "type": [ "integer", "null" ] }, "fromUser": { "type": [ "string", "null" ] }, "toUser": { "type": [ "string", "null" ] }, "ruriUser": { "type": [ "string", "null" ] }, "raw": { "type": [ "string", "null" ], "description": "Raw SIP message returned by Homer when available." } } }, "SipHeaderMapping": { "type": "object", "required": [ "providerHeader", "retellHeader", "direction" ], "properties": { "providerHeader": { "type": "string", "description": "Header name received from or written toward the SIP provider." }, "retellHeader": { "type": "string", "pattern": "^(X-[A-Za-z0-9_-]+|P-Asserted-Identity)$", "description": "Retell-visible X-* or P-Asserted-Identity header." }, "direction": { "type": "string", "enum": [ "inbound", "bidirectional" ] } } }, "PhoneNumberRetellWorkspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phoneNumberId": { "type": "string", "format": "uuid" }, "retellWorkspaceId": { "type": "string", "format": "uuid" }, "friendlyName": { "type": [ "string", "null" ] }, "retellImportIdentifier": { "type": "string" }, "inboundAgents": { "type": "array", "items": { "$ref": "#/components/schemas/RetellAgentWeight" } }, "failoverAgents": { "type": "array", "items": { "$ref": "#/components/schemas/RetellAgentWeight" } }, "failoverEnabled": { "type": "boolean" }, "enabled": { "type": "boolean" }, "retellImportStatus": { "type": "string" }, "retellLastError": { "type": [ "string", "null" ] }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/RetellWorkspace" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SipCustomHeader": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9-]+$" }, "value": { "type": "string" } } }, "OutboundCallTag": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Dotted path into the Retell create-phone-call payload (for example agent_override.agent.voice_id)." }, "value": { "type": "string", "description": "Raw value or JSON text parsed as booleans, numbers, arrays, or objects." } } }, "RetellAgentWeight": { "type": "object", "required": [ "agentId", "weight" ], "properties": { "agentId": { "type": "string" }, "agentVersion": { "type": [ "integer", "string", "null" ] }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } } }, "RetellWorkspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "friendlyName": { "type": "string" }, "importPrefix": { "type": "string", "description": "Prefix used when importing the same SIP number into this Retell workspace." }, "tokenFirst6": { "type": [ "string", "null" ] }, "tokenLast4": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "validatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "monthlyPriceCents": { "type": "integer", "readOnly": true, "description": "Current additional-workspace amount from the active BillingPriceConfig catalog." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }