{ "openapi": "3.0.3", "info": { "title": "phonr.xyz REST API", "version": "1.0.0", "description": "Bearer-protected calling API. Preview does not dial. POST /calls places a real call. Only one call may be active; reuse Idempotency-Key with the same brief after uncertainty. Audio links are relative to the server origin. The HTTPS tunnel exposes /v1; the dashboard remains local." }, "servers": [ { "url": "/v1", "description": "Current server (local or HTTPS tunnel)" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/status": { "get": { "operationId": "getStatus", "summary": "Read readiness and server call settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/templates": { "get": { "operationId": "getTemplates", "summary": "List editable purpose templates", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "purpose": { "type": "string" }, "to": { "type": "string" }, "language": { "type": "string" }, "note": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/preview": { "post": { "operationId": "previewCall", "summary": "Preview instructions without external requests or dialing", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "$ref": "#/components/schemas/PreviewBrief" }, "prompt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewBrief" } } } } } }, "/calls": { "get": { "operationId": "listCalls", "summary": "List calls, newest first", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "total": { "type": "integer" }, "nextOffset": { "type": "integer", "nullable": true } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "requestId", "in": "query", "schema": { "type": "string" } } ] }, "post": { "operationId": "startCall", "summary": "Place a real call or return the same idempotent request", "responses": { "200": { "description": "Existing call for the same request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "201": { "description": "New call record; inspect call.status for startup failures or uncertainty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }, "headers": { "Location": { "schema": { "type": "string" }, "description": "Relative call resource URL" } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]{16,80}$" }, "description": "Persist and reuse with the same brief after a timeout. A changed brief with the same key conflicts." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brief" } } } } } }, "/calls/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getCall", "summary": "Read call status, transcript, result, and audio links", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}/stop": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "stopCall", "summary": "Stop the call and return its latest status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/calls/{id}/reconcile": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "reconcileCall", "summary": "Check provider status without redialing", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/calls/{id}/clips": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listClips", "summary": "List completed clips in capture order", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clips": { "type": "array", "items": { "$ref": "#/components/schemas/Clip" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}/recording": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "downloadRecording", "summary": "Download WAV audio with bearer authentication", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "example": "bytes=0-43" } ], "responses": { "200": { "description": "Full WAV", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid or unavailable byte range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{id}/clips/{name}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}\\.wav$", "example": "0000.wav" } } ], "get": { "operationId": "downloadClip", "summary": "Download WAV audio with bearer authentication", "parameters": [ { "name": "Range", "in": "header", "schema": { "type": "string" }, "example": "bytes=0-43" } ], "responses": { "200": { "description": "Full WAV", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Requested byte range", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or incorrect bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call or audio not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong HTTP method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active call or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body over 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON content type required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid or unavailable byte range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Operation failed; inspect call before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "REST disabled or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The PHONER_API_KEY configured on the server. Send it only in the Authorization header." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Brief": { "type": "object", "properties": { "to": { "type": "string", "example": "+14155550123", "description": "Phone number with country code. Caller number is configured on the server." }, "purpose": { "type": "string", "minLength": 5, "maxLength": 6000 }, "language": { "type": "string", "minLength": 2, "maxLength": 80, "example": "English" }, "systemMessage": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "to", "purpose", "language" ], "additionalProperties": false }, "PreviewBrief": { "type": "object", "properties": { "to": { "type": "string", "description": "Phone number with country code, or empty." }, "purpose": { "type": "string", "maxLength": 6000 }, "language": { "type": "string", "maxLength": 80, "default": "English" }, "systemMessage": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "additionalProperties": false }, "Result": { "type": "object", "properties": { "status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "string" }, "next_steps": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } } }, "nullable": true, "description": "New result statuses: completed, partial, needs_user. Older rental records retain their legacy fields and statuses." }, "Call": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestId": { "type": "string" }, "status": { "type": "string" }, "terminal": { "type": "boolean" }, "from": { "type": "string", "nullable": true }, "to": { "type": "string" }, "provider": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "duration": { "type": "number", "nullable": true }, "brief": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Brief" } ], "description": "Null for older rental histories without a generic call brief." }, "result": { "$ref": "#/components/schemas/Result" }, "problem": { "type": "string", "nullable": true }, "transcript": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Included on single-call responses, omitted in lists." }, "recording": { "type": "object", "properties": { "status": { "type": "string" }, "clipCount": { "type": "integer" }, "download": { "type": "string", "nullable": true }, "clips": { "type": "string" } } }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "stop": { "type": "string" }, "reconcile": { "type": "string" } } } }, "required": [ "id", "requestId", "status", "terminal", "to", "createdAt", "recording", "links" ] }, "CallResponse": { "type": "object", "properties": { "call": { "$ref": "#/components/schemas/Call" } }, "required": [ "call" ] }, "Clip": { "type": "object", "properties": { "name": { "type": "string" }, "index": { "type": "integer", "nullable": true }, "startSeconds": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "download": { "type": "string" } }, "required": [ "name", "download" ] }, "Status": { "type": "object", "properties": { "ready": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ok": { "type": "boolean" }, "hint": { "type": "string" } } } }, "provider": { "type": "string" }, "from": { "type": "string", "nullable": true }, "model": { "type": "string" }, "maxSeconds": { "type": "integer" }, "recordingMode": { "type": "string", "enum": [ "immediate", "consent" ] }, "activeCallId": { "type": "string", "nullable": true }, "defaultSystemMessage": { "type": "string" } } } } } }