{ "openapi": "3.1.0", "info": { "title": "RealVoice Partner API", "version": "1.0.0", "description": "Managed partner access. Deployment and staff-issued credentials required. Provider and customer organizations must be active. All durable mutations require Idempotency-Key; webhook verification is safe to repeat. Rate limit: 120 requests per minute per API key. Live audio does not traverse this API." }, "servers": [ { "url": "https://{project_ref}.supabase.co/functions/v1/partner-api/v1", "variables": { "project_ref": { "default": "njvewlwnppamxgdaapjs" } }, "description": "RealVoice production partner API" } ], "security": [ { "partnerKey": [] } ], "paths": { "/customers/{customer_id}/agents": { "get": { "summary": "List agents", "description": "Required scope: agents:read.", "operationId": "list_agents", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/agents/{id}": { "get": { "summary": "Get agent", "description": "Required scope: agents:read.", "operationId": "get_agents", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } }, "patch": { "summary": "Request an agent configuration change", "description": "Required scope: agents:write. Creates a pending staff review. No immediate live change.", "operationId": "request_agent_change", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPatch" } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAccepted" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/knowledge": { "get": { "summary": "List knowledge", "description": "Required scope: knowledge:read.", "operationId": "list_knowledge", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Knowledge" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } }, "post": { "summary": "Submit knowledge for review", "description": "Required scope: knowledge:write.", "operationId": "request_knowledge", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeInput" } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAccepted" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/knowledge/{id}": { "get": { "summary": "Get knowledge source", "description": "Required scope: knowledge:read.", "operationId": "get_knowledge", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Knowledge" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/calls": { "get": { "summary": "List calls", "description": "Required scope: calls:read.", "operationId": "list_calls", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/calls/{id}": { "get": { "summary": "Get call", "description": "Required scope: calls:read.", "operationId": "get_calls", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Call" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/requests": { "get": { "summary": "List requests", "description": "Required scope: requests:read.", "operationId": "list_requests", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewRequest" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/requests/{id}": { "get": { "summary": "Get request", "description": "Required scope: requests:read.", "operationId": "get_requests", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReviewRequest" } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/customers/{customer_id}/agents/{id}/publish": { "post": { "summary": "Request agent publication", "description": "Required scope: agents:write. Publication runs only after staff approval through existing engine checks.", "operationId": "request_publish", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAccepted" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Other fields are rejected.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } } } }, "/customers/{customer_id}/usage": { "get": { "summary": "Read usage ledger totals", "description": "Required scope: usage:read.", "operationId": "get_usage", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "description": "URL-encoded external customer ID assigned by RealVoice staff.", "schema": { "type": "string", "minLength": 1, "maxLength": 160 } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Inclusive UTC start, ending in Z." }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Exclusive UTC endpoint. Range must be at most 93 days." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Usage" } }, "currency": { "type": "null", "description": "The existing usage ledger does not store currency. Use the finalized invoice for currency and amount due." }, "pricing_note": { "type": "string" } }, "required": [ "customer_id", "from", "to", "data", "currency", "pricing_note" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/webhooks": { "get": { "summary": "List webhook receivers", "description": "Required scope: webhooks:read.", "operationId": "list_webhooks", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } }, "post": { "summary": "Register a webhook receiver", "description": "Required scope: webhooks:write. Registers a pending HTTPS receiver. Verify ownership before call events can be delivered. To rotate the signing secret at the same URL, disable the old endpoint first, then create and verify a new endpoint. Up to 10 pending or active endpoints are allowed per provider.", "operationId": "create_webhook", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "signing_secret": { "type": "string", "description": "Store in the receiving server. Returned on creation and exact creation retries only." } }, "required": [ "endpoint", "signing_secret" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/webhooks/{id}": { "patch": { "summary": "Change a webhook receiver URL", "description": "Required scope: webhooks:write. Resets ownership verification. Disabled endpoints cannot be reactivated.", "operationId": "update_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "endpoint" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } }, "delete": { "summary": "Disable a webhook receiver", "description": "Required scope: webhooks:write.", "operationId": "disable_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "endpoint" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Other fields are rejected.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } } } }, "/webhooks/{id}/verify": { "post": { "summary": "Verify receiver ownership", "description": "Required scope: webhooks:write. Sends a signed webhook.verification event with a challenge. Receiver must return HTTP 2xx JSON with the identical challenge. Safe to repeat; an active receiver returns verified immediately.", "operationId": "verify_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true } }, "required": [ "verified" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Receiver did not return JSON containing the exact verification challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "502": { "description": "Receiver connection failed, timed out, returned a non-2xx response, or exceeded the response size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Other fields are rejected.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } } } }, "/deliveries": { "get": { "summary": "List delivery attempts", "description": "Required scope: webhooks:read.", "operationId": "list_deliveries", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/deliveries/{id}/retry": { "post": { "summary": "Retry a failed or dead delivery", "description": "Required scope: webhooks:write. Only failed or dead jobs with retained payloads and an active verified endpoint can be retried.", "operationId": "retry_delivery", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{8,128}$" }, "description": "Same key and normalized operation/body returns original response. Different body with same key returns 409. Keep the same API credential for retries." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "queued" } }, "required": [ "id", "status" ] } }, "required": [ "delivery" ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Malformed request or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "description": "Invalid, expired or revoked key; provider is not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "403": { "description": "Required scope missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "404": { "description": "Resource or active customer mapping not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "409": { "description": "Conflict, disabled resource or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "410": { "description": "Delivery content has expired under the customer retention policy and cannot be retried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "413": { "description": "Request body exceeds this operation's byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "description": "Per-key rate limit; retry after 60 seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "503": { "description": "Required service configuration missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } }, "requestBody": { "required": false, "description": "Omit the body or send an empty JSON object. Other fields are rejected.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } } } } }, "components": { "securitySchemes": { "partnerKey": { "type": "http", "scheme": "bearer", "description": "Scoped rvp_ partner key. Never use a platform-owner rvk_ key or Supabase service-role key." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } } } }, "AgentPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "maxLength": 60, "minLength": 1 }, "greeting": { "type": "string", "maxLength": 400, "minLength": 1 }, "speaking_style": { "type": "string", "maxLength": 600, "minLength": 0 }, "business_context": { "type": "string", "maxLength": 6000, "minLength": 0 }, "escalation": { "type": "string", "maxLength": 1000, "minLength": 0 }, "language": { "type": "string", "maxLength": 5, "minLength": 1, "enum": [ "af", "ar", "hy", "as", "az", "be", "bn", "bs", "bg", "ca", "ceb", "ny", "hr", "cs", "da", "nl", "en", "et", "fil", "fi", "fr", "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id", "ga", "it", "ja", "jv", "kn", "kk", "ky", "ko", "lv", "ln", "lt", "lb", "mk", "ms", "ml", "zh", "mr", "ne", "no", "ps", "fa", "pl", "pt", "pa", "ro", "ru", "sr", "sd", "sk", "sl", "so", "es", "sw", "sv", "ta", "te", "th", "tr", "uk", "ur", "vi", "cy" ] } }, "description": "Strings are trimmed before validation. At least one supported field is required." }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "type": "string" }, "greeting": { "type": "string" }, "language": { "type": "string" }, "speaking_style": { "type": [ "string", "null" ] }, "business_context": { "type": [ "string", "null" ] }, "escalation": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "current_version": { "type": "integer" }, "needs_sync": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "role", "greeting", "language", "speaking_style", "business_context", "escalation", "status", "current_version", "needs_sync", "updated_at" ] }, "KnowledgeInput": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "kind" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 200000 }, "kind": { "type": "string", "enum": [ "text", "faq", "manual" ] }, "category": { "type": "string", "maxLength": 40, "default": "company", "minLength": 1 }, "language": { "type": "string", "maxLength": 5, "default": "en", "enum": [ "af", "ar", "hy", "as", "az", "be", "bn", "bs", "bg", "ca", "ceb", "ny", "hr", "cs", "da", "nl", "en", "et", "fil", "fi", "fr", "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id", "ga", "it", "ja", "jv", "kn", "kk", "ky", "ko", "lv", "ln", "lt", "lb", "mk", "ms", "ml", "zh", "mr", "ne", "no", "ps", "fa", "pl", "pt", "pa", "ro", "ru", "sr", "sd", "sk", "sl", "so", "es", "sw", "sv", "ta", "te", "th", "tr", "uk", "ur", "vi", "cy" ], "minLength": 1 }, "supersedes_id": { "type": "string", "format": "uuid" } }, "description": "Strings are trimmed before validation. A replacement source must belong to this customer." }, "Knowledge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "kind": { "type": "string" }, "category": { "type": "string" }, "language": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "chunk_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "kind", "category", "language", "status", "version", "chunk_count", "created_at", "updated_at" ] }, "Call": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "direction": { "type": "string" }, "from_e164": { "type": [ "string", "null" ] }, "to_e164": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_seconds": { "type": [ "integer", "null" ] }, "summary": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "resolved": { "type": [ "boolean", "null" ] }, "human_required": { "type": [ "boolean", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_id", "direction", "from_e164", "to_e164", "status", "started_at", "ended_at", "duration_seconds", "summary", "outcome", "resolved", "human_required", "created_at" ] }, "ReviewRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "agent.update", "knowledge.add", "agent.publish" ] }, "status": { "enum": [ "pending", "processing", "approved", "rejected", "failed" ] }, "payload": { "type": "object" }, "review_note": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ], "description": "Approval result containing resource IDs and publication state; null before approval." }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "org_id", "kind", "status", "payload", "review_note", "result", "error", "created_at", "updated_at", "reviewed_at" ] }, "ReviewAccepted": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "agent.update", "knowledge.add", "agent.publish" ] }, "status": { "const": "pending" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "status", "created_at" ] } }, "required": [ "request" ] }, "WebhookInput": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Public HTTPS DNS name, port 443, no credentials or fragment. All resolved IPs must be public. Redirects are rejected." } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partner_org_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "status": { "enum": [ "pending", "active", "disabled" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "partner_org_id", "url", "status", "verified_at", "created_at", "updated_at" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "queued", "running", "done", "failed", "dead" ] }, "attempts": { "type": "integer" }, "run_after": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "endpoint_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string" }, "customer_id": { "type": "string" } }, "required": [ "id", "status", "attempts", "run_after", "last_error", "created_at", "endpoint_id", "event_id", "customer_id" ] }, "Usage": { "type": "object", "properties": { "kind": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" }, "events": { "type": "integer" }, "billable_quantity": { "type": "number" }, "billable_events": { "type": "integer" }, "price_cents": { "type": "number" }, "unpriced_events": { "type": "integer", "description": "Billable events without a recorded price; totals are incomplete until priced." } }, "required": [ "kind", "unit", "quantity", "events", "billable_quantity", "billable_events", "price_cents", "unpriced_events" ] } }, "headers": { "RequestId": { "description": "Unique request identifier, including on error responses.", "schema": { "type": "string", "format": "uuid" } }, "IdempotencyReplayed": { "description": "True when returning a previously committed response for this credential and idempotency key.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, "RetryAfter": { "description": "Seconds to wait before retrying a rate-limited request.", "schema": { "type": "integer", "const": 60 } } } } }