{ "openapi": "3.1.0", "info": { "title": "Speak Agent API", "version": "2026-07-24", "description": "Create, configure, and test voice agents over HTTP.\n\nThis reference covers the agent-scoped surface only: agents, their sub-resources, and test suites. Workspace, team, billing, telephony, and conversation endpoints are deliberately out of scope." }, "servers": [ { "url": "https://api.speakai.co", "description": "Production" }, { "url": "http://localhost:3001", "description": "Local development" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key in the form sk_live_ followed by 64 hex characters. Create one at Dashboard → Developers → API Keys." } } }, "tags": [ { "name": "Finding your workspace id", "description": "Not an agent endpoint, but you need it before anything else works. This is the only call that does not require the X-Workspace-Id header." }, { "name": "Agents", "description": "Create, read, update, publish, and delete agents." }, { "name": "Test suites", "description": "Define scenarios and grading criteria for an agent, then run them and read the scores. Every endpoint here requires X-Workspace-Id, and every response nests its payload under data." }, { "name": "Agent resources", "description": "Links and documents the agent can surface during a conversation. All of these require X-Workspace-Id." }, { "name": "Sharing and the widget", "description": "Publish an agent as a public widget and control how the bubble looks. These endpoints authenticate with the key but do not consult X-Workspace-Id." }, { "name": "Pronunciation", "description": "Teach the agent how to say brand names and jargon. Rules sync to ElevenLabs when that is the configured voice provider." }, { "name": "Data collection fields", "description": "Fields the agent gathers during a conversation. Fields are instances of a shared template." } ], "paths": { "/api/org": { "get": { "operationId": "list-workspaces", "summary": "List the workspaces your key can reach", "description": "Returns every workspace the key's user is a member of, with your role and the agent count in each. Use the orgId field as X-Workspace-Id on all later calls.", "tags": [ "Finding your workspace id" ], "parameters": [], "responses": { "200": { "description": "Workspaces the key's user belongs to.", "content": { "application/json": { "example": { "success": true, "workspaces": [ { "orgId": "a1013f16-7149-4f28-b190-c51a0fd29ed5", "name": "Acme Workspace", "slug": "acme-workspace", "ownerId": "bbf36313-fad0-498d-b965-427568726d3d", "members": [ { "userId": "bbf36313-fad0-498d-b965-427568726d3d", "email": "you@example.com", "role": "owner", "joinedAt": "2026-02-26T15:54:56.496Z" } ], "myRole": "owner", "agentCount": 2 } ] } } } } } } }, "/api/agents": { "get": { "operationId": "list-agents", "summary": "List agents", "description": "With X-Workspace-Id, returns every agent in that workspace. Without it, falls back to agents owned by the key's user — which is usually the same set but not guaranteed, so send the header.", "tags": [ "Agents" ], "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Agents, newest first.", "content": { "application/json": { "example": { "success": true, "agents": [ { "agentId": "e666809a-65c6-4c58-9690-19b3d83e7133", "name": "Nimbus from Nimbus Labs", "status": "active", "orgId": "a1013f16-7149-4f28-b190-c51a0fd29ed5", "userId": "bbf36313-fad0-498d-b965-427568726d3d", "conversationMode": "voice" } ] } } } } } }, "post": { "operationId": "create-agent", "summary": "Create an agent", "description": "Only name is meaningfully required — every other field falls back to a default. X-Workspace-Id is effectively required: without it the request fails with a 500 from the database layer.", "tags": [ "Agents" ], "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Not enforced by middleware, but the request fails at the database layer without it." } ], "responses": { "201": { "description": "Created. The response contains the fully defaulted agent.", "content": { "application/json": { "example": { "success": true, "agent": { "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a", "name": "Support Agent", "personality": "friendly and concise", "instructions": "Answer billing questions. Escalate refunds to a human.", "status": "active", "conversationMode": "voice", "creativityLevel": 0.5, "stt": { "provider": "deepgram", "model": "nova-3", "lexiconTerms": [] }, "voice": { "provider": "elevenlabs", "voiceId": "21m00Tcm4TlvDq8ikWAM", "pronunciationSyncFailed": false }, "llm": { "provider": "openai", "model": "gpt-5.4" }, "chatSettings": { "welcomeMessage": "Hi, how can I help?", "conversationStarters": [], "topicsToAvoid": [], "maxSessionLength": 3, "language": "en-US", "maxResponseLength": 30 }, "shareSettings": { "isPublic": false, "allowedDomains": [] }, "isDeleted": false, "createdAt": "2026-07-24T19:37:36.742Z" } } } } }, "500": { "description": "X-Workspace-Id was missing.", "content": { "application/json": { "example": { "success": false, "error": "Failed to create agent", "message": "Agent validation failed: orgId: Org ID is required" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name.", "type": "string" }, "personality": { "description": "Tone and character. Defaults to \"Friendly and helpful assistant\".", "type": "string" }, "instructions": { "description": "The system prompt. Defaults to \"You are a helpful AI assistant.\"", "type": "string" }, "conversationMode": { "description": "voice or avatar. Defaults to voice.", "type": "string" }, "creativityLevel": { "description": "0 to 1. Defaults to 0.5.", "type": "number" }, "chatSettings": { "description": "welcomeMessage, conversationStarters, maxResponseLength (10-50), topicsToAvoid, maxSessionLength, language.", "type": "object" }, "recordingEnabled": { "description": "Defaults to false.", "type": "boolean" }, "websiteUrl": { "description": "Validated as a URL when present.", "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Support Agent", "personality": "friendly and concise", "instructions": "Answer billing questions. Escalate refunds to a human.", "voice": { "provider": "elevenlabs", "voiceId": "21m00Tcm4TlvDq8ikWAM" }, "llm": { "provider": "openai", "model": "gpt-5.4" }, "chatSettings": { "welcomeMessage": "Hi, how can I help?", "maxResponseLength": 30, "language": "en-US" } } } } } } }, "/api/agents/{id}": { "get": { "operationId": "get-agent", "summary": "Get one agent", "description": "Returns the full agent document. Draft agents automatically include their generation state; add ?include=generation to force it on an active agent.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId (a UUID), not the Mongo _id." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Set to generation to attach the AI generation record." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The agent.", "content": { "application/json": { "example": { "success": true, "agent": { "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a", "name": "Docs Probe", "status": "active" } } } } }, "404": { "description": "No such agent in scope.", "content": { "application/json": { "example": { "success": false, "error": "Agent not found" } } } } } }, "put": { "operationId": "update-agent", "summary": "Update an agent", "description": "Partial update at the top level: fields you omit are left alone. Nested objects are the trap — everything except voice is replaced wholesale.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The updated agent.", "content": { "application/json": { "example": { "success": true, "agent": { "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a", "name": "Support Agent v2", "creativityLevel": 0.8 } } } } }, "400": { "description": "A validation error the server considers user-facing, such as a phone number already assigned to another agent.", "content": { "application/json": { "example": { "success": false, "error": "Phone number is already assigned to another agent" } } } }, "404": { "description": "No such agent in scope.", "content": { "application/json": { "example": { "success": false, "error": "Agent not found" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "name": "Support Agent v2", "creativityLevel": 0.8, "voice.voiceId": "NEW_VOICE_ID" } } } } }, "delete": { "operationId": "delete-agent", "summary": "Delete an agent", "description": "Soft delete. The document stays in the database with isDeleted true and a deletedAt timestamp, and disappears from every read.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "example": { "success": true, "message": "Agent deleted successfully" } } } }, "404": { "description": "Already deleted, or never existed.", "content": { "application/json": { "example": { "success": false, "error": "Agent not found" } } } } } } }, "/api/agents/{id}/save-draft": { "post": { "operationId": "save-draft", "summary": "Save draft changes", "description": "Same update semantics as PUT, but intended for in-progress edits during the build flow. Returns the agent rather than a status-only body.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The saved agent.", "content": { "application/json": { "example": { "success": true, "agent": { "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a" } } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "personality": "calm and concise" } } } } } }, "/api/agents/{id}/publish": { "post": { "operationId": "publish-agent", "summary": "Publish an agent", "description": "Moves the agent to active so it can take conversations. Takes no body. Publishing an already-active agent is harmless.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The published agent.", "content": { "application/json": { "example": { "success": true, "agent": { "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a", "status": "active" } } } } }, "404": { "description": "Not found or not publishable.", "content": { "application/json": { "example": { "success": false, "error": "Agent not found or not ready to publish" } } } } } } }, "/api/testing/{agentId}/suite": { "get": { "operationId": "get-suite", "summary": "Get the test suite", "description": "Returns null when the agent has no suite yet, with a 200 rather than a 404.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The suite, or null.", "content": { "application/json": { "example": { "success": true, "data": { "suite": null } } } } }, "403": { "description": "The agent belongs to a different workspace.", "content": { "application/json": { "example": { "success": false, "error": "Forbidden" } } } } } }, "put": { "operationId": "update-suite", "summary": "Create or replace the test suite", "description": "Creates the suite if none exists, otherwise updates it. Top-level fields you omit are preserved, so sending only maxCostPerRun keeps your scenarios. Unknown fields are rejected outright.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The saved suite.", "content": { "application/json": { "example": { "success": true, "data": { "suite": { "suiteId": "7ea03962-42a9-4e0a-b382-9030a5b1d895", "agentId": "3f5e236b-204f-4ae1-bb93-02ba694e636a", "orgId": "a1013f16-7149-4f28-b190-c51a0fd29ed5", "scenarios": [ { "scenarioId": "greeting-1", "name": "Greets the caller", "isEnabled": true, "category": "greeting" } ], "maxCostPerRun": 1, "autoRunOnKbUpdate": false, "autoRunOnInstructionSave": false, "scheduledCron": null } } } } } }, "400": { "description": "Validation failed. The message names the offending path.", "content": { "application/json": { "example": { "success": false, "error": "\"scenarios[0].userMessages\" must contain at least 1 items" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scenarios": { "description": "Test scenarios. See the scenario fields below.", "type": "array", "items": { "type": "object" } }, "maxCostPerRun": { "description": "0 to 100, in dollars. The run aborts if it would exceed this.", "type": "number" }, "autoRunOnKbUpdate": { "description": "Start a run when the knowledge base changes.", "type": "boolean" }, "autoRunOnInstructionSave": { "description": "Start a run when instructions, personality, or chatSettings change.", "type": "boolean" }, "scheduledCron": { "description": "Cron expression for scheduled runs, or null.", "type": [ "string", "null" ] } }, "required": [] }, "example": { "scenarios": [ { "scenarioId": "greeting-1", "name": "Greets the caller", "description": "Agent should greet and offer help", "userMessages": [ "Hi there" ], "criteria": [ { "criterionId": "c1", "name": "Greeting present", "evaluationPrompt": "Did the agent greet the user and offer help?", "weight": 5, "isCritical": true, "type": "llm_judged" } ], "category": "greeting", "isEnabled": true } ], "maxCostPerRun": 1, "autoRunOnKbUpdate": false, "autoRunOnInstructionSave": false, "scheduledCron": null } } } } } }, "/api/testing/{agentId}/suite/generate": { "post": { "operationId": "generate-suite", "summary": "Generate a default suite", "description": "Uses an LLM to derive scenarios from the agent's own configuration and saves them. This overwrites the existing scenarios array. Takes no body and costs a model call.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The generated suite.", "content": { "application/json": { "example": { "success": true, "data": { "suite": { "suiteId": "7ea03962-42a9-4e0a-b382-9030a5b1d895", "scenarios": [] } } } } } } } } }, "/api/testing/{agentId}/run": { "post": { "operationId": "start-run", "summary": "Start a test run", "description": "Creates the run and returns immediately; scenarios execute in the background. This spends credits and calls your configured model and voice providers.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The run record, already in progress.", "content": { "application/json": { "example": { "success": true, "data": { "run": { "runId": "…", "status": "running", "trigger": "manual" } } } } } }, "404": { "description": "The agent has no suite.", "content": { "application/json": { "example": { "success": false, "error": "No test suite configured" } } } }, "409": { "description": "A run is already active, credits are insufficient, or no scenario is enabled.", "content": { "application/json": { "example": { "success": false, "error": "Insufficient credits" } } } } } } }, "/api/testing/{agentId}/run/active": { "get": { "operationId": "active-run", "summary": "Get the active run", "description": "Returns the running or paused run, or null when nothing is in flight.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The active run, or null.", "content": { "application/json": { "example": { "success": true, "data": { "run": null } } } } } } } }, "/api/testing/{agentId}/run/{runId}/pause": { "post": { "operationId": "pause-run", "summary": "Pause a run", "description": "Stops after the current scenario finishes. Takes no body.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The runId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Paused.", "content": { "application/json": { "example": { "success": true } } } }, "404": { "description": "No such run in this workspace.", "content": { "application/json": { "example": { "success": false, "error": "Run not found" } } } } } } }, "/api/testing/{agentId}/run/{runId}/resume": { "post": { "operationId": "resume-run", "summary": "Resume a run", "description": "Continues a paused run from where it stopped. Takes no body.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The runId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Resumed.", "content": { "application/json": { "example": { "success": true } } } } } } }, "/api/testing/{agentId}/run/{runId}/cancel": { "post": { "operationId": "cancel-run", "summary": "Cancel a run", "description": "Ends the run permanently. Scenarios already scored keep their results. Takes no body.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The runId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "example": { "success": true } } } } } } }, "/api/testing/{agentId}/runs": { "get": { "operationId": "list-runs", "summary": "List past runs", "description": "Newest first.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Defaults to 20, capped at 100." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The runs.", "content": { "application/json": { "example": { "success": true, "data": { "runs": [] } } } } } } } }, "/api/testing/{agentId}/runs/{runId}": { "get": { "operationId": "get-run", "summary": "Get one run in full", "description": "Includes per-scenario results, per-criterion scores, and any recommendations produced by the run.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The runId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "example": { "success": true, "data": { "run": { "runId": "…", "status": "completed", "overallScore": 86 } } } } } }, "404": { "description": "No such run in this workspace.", "content": { "application/json": { "example": { "success": false, "error": "Run not found" } } } } } } }, "/api/testing/{agentId}/runs/{runId}/recommendations/{recId}/apply": { "post": { "operationId": "apply-recommendation", "summary": "Apply a recommendation", "description": "Writes a run's suggested fix into the agent configuration. Takes no body. This mutates the agent.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The runId." }, { "name": "recId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The recommendation id from the run detail." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Applied.", "content": { "application/json": { "example": { "success": true, "data": {} } } } }, "400": { "description": "The recommendation carries no actionable fix.", "content": { "application/json": { "example": { "success": false, "error": "Recommendation has no suggested fix" } } } }, "404": { "description": "Run or recommendation not found.", "content": { "application/json": { "example": { "success": false, "error": "Recommendation not found" } } } } } } }, "/api/testing/{agentId}/baseline": { "get": { "operationId": "get-baseline", "summary": "Get the baseline", "description": "The reference snapshot later runs are compared against. Null until a baseline is set.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The baseline, or null.", "content": { "application/json": { "example": { "success": true, "data": { "baseline": null } } } } } } } }, "/api/testing/{agentId}/score-history": { "get": { "operationId": "score-history", "summary": "Get score history", "description": "Flattened points for charting: runId, score, timestamp, and what triggered the run.", "tags": [ "Test suites" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The history.", "content": { "application/json": { "example": { "success": true, "data": { "history": [ { "runId": "…", "score": 86, "timestamp": "2026-07-24T19:38:48.792Z", "trigger": "manual" } ] } } } } } } } }, "/api/agents/{agentId}/resources": { "get": { "operationId": "list-resources", "summary": "List resources", "description": "Paginated, with optional text search.", "tags": [ "Agent resources" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Defaults to 1." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1 to 100. Defaults to 10." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text filter." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "The resources.", "content": { "application/json": { "example": { "success": true, "data": { "resources": [], "total": 0, "page": 1, "limit": 10 } } } } } } }, "post": { "operationId": "create-resource", "summary": "Add a resource", "description": "All four of url, title, description, and action are required.", "tags": [ "Agent resources" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "example": { "success": true, "data": { "resource": { "resourceId": "…" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Must be a valid URI.", "type": "string" }, "title": { "description": "Up to 200 characters.", "type": "string" }, "description": { "description": "Up to 1000 characters.", "type": "string" }, "action": { "description": "link or presentation.", "type": "string" }, "contentType": { "description": "video, pdf, or image.", "type": "string" } }, "required": [ "url", "title", "description", "action" ] }, "example": { "url": "https://example.com/pricing", "title": "Pricing page", "description": "Current plans and prices", "action": "link" } } } } } }, "/api/agents/{agentId}/resources/bulk": { "post": { "operationId": "bulk-create-resources", "summary": "Add resources in bulk", "description": "Between 1 and 100 resources per call, each with the same field rules as a single create.", "tags": [ "Agent resources" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "example": { "success": true, "data": { "created": 1 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "description": "1 to 100 resource objects.", "type": "array", "items": { "type": "object" } } }, "required": [ "resources" ] }, "example": { "resources": [ { "url": "https://example.com/docs", "title": "Docs", "description": "Product documentation", "action": "link" } ] } } } } } }, "/api/agents/{agentId}/resources/{resourceId}": { "put": { "operationId": "update-resource", "summary": "Update a resource", "description": "Send at least one field. All fields are optional individually.", "tags": [ "Agent resources" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resourceId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Updated.", "content": { "application/json": { "example": { "success": true, "data": { "resource": {} } } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "title": "Pricing (2026)" } } } } }, "delete": { "operationId": "delete-resource", "summary": "Delete a resource", "description": "Soft delete, same as agents.", "tags": [ "Agent resources" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The resourceId." }, { "name": "X-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "example": { "success": true } } } } } } }, "/api/agents/{id}/share": { "post": { "operationId": "create-share", "summary": "Create or update the share link", "description": "Returns a long-lived share token plus a short code and a ready-made widget URL.", "tags": [ "Sharing and the widget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." } ], "responses": { "200": { "description": "The share details.", "content": { "application/json": { "example": { "success": true, "shareToken": "b5a4a9bc11e6ff2f40e70448ecc0f9e153f5d283416dbfd663a4b134cd424a8e", "shareLink": "https://agents.speakai.co/widget/nkqOg5iJtU", "shortCode": "nkqOg5iJtU" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "description": "Whether the link works without further auth.", "type": "boolean" }, "allowedDomains": { "description": "Restrict embedding to these origins.", "type": "array", "items": { "type": "string" } }, "expiresAt": { "description": "ISO timestamp after which the link stops working.", "type": "string" } }, "required": [] }, "example": { "isPublic": true, "allowedDomains": [ "example.com" ] } } } } }, "delete": { "operationId": "revoke-share", "summary": "Revoke the share link", "description": "Invalidates the token and short code immediately.", "tags": [ "Sharing and the widget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "example": { "success": true } } } } } } }, "/api/agents/{id}/widget-config": { "patch": { "operationId": "widget-config", "summary": "Update widget appearance", "description": "Partial update of shareSettings.widgetConfig. Returns a message rather than the agent.", "tags": [ "Sharing and the widget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." } ], "responses": { "200": { "description": "Updated.", "content": { "application/json": { "example": { "success": true, "message": "Widget config updated successfully" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayMode": { "description": "floating or inline.", "type": "string" }, "position": { "description": "bottom-left or bottom-right.", "type": "string" }, "theme": { "description": "light, dark, or auto.", "type": "string" }, "buttonSize": { "description": "small, medium, or large.", "type": "string" }, "bubbleIconType": { "description": "avatar or generic.", "type": "string" }, "buttonColor": { "description": "CSS colour.", "type": "string" }, "backgroundColor": { "description": "CSS colour.", "type": "string" }, "fontFamily": { "description": "CSS font stack.", "type": "string" }, "borderRadius": { "description": "Pixels.", "type": "number" }, "compactMode": { "description": "Denser layout.", "type": "boolean" }, "showAvatar": { "description": "Show the avatar in the panel.", "type": "boolean" }, "voiceEnabled": { "description": "Offer voice mode.", "type": "boolean" }, "enableUserCamera": { "description": "Ask for the visitor's camera.", "type": "boolean" }, "chatOpenByDefault": { "description": "Open the panel on load.", "type": "boolean" } }, "required": [] }, "example": { "theme": "dark", "position": "bottom-left" } } } } } }, "/api/agents/{id}/pronunciation": { "get": { "operationId": "get-pronunciation", "summary": "Get pronunciation rules", "description": "Returns the rules and the ElevenLabs sync state. syncStatus is not_applicable when the agent does not use ElevenLabs.", "tags": [ "Pronunciation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Rules and sync state.", "content": { "application/json": { "example": { "success": true, "rules": [], "elevenLabsDictId": null, "elevenLabsVersionId": null, "syncedAt": null, "syncStatus": "not_applicable" } } } } } }, "put": { "operationId": "update-pronunciation", "summary": "Replace pronunciation rules", "description": "Replaces the whole rule set, up to 500 rules, then syncs to the provider. Alias rules must be plain English respelling — IPA characters are rejected, because the voice models in use would read them aloud literally.", "tags": [ "Pronunciation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Saved and synced.", "content": { "application/json": { "example": { "success": true, "rules": [ { "term": "Mitrex", "pronounceAs": "mih-TREKS" } ] } } } }, "400": { "description": "IPA characters were found in an alias rule.", "content": { "application/json": { "example": { "success": false, "error": "Pronunciation must use plain English respelling, not IPA. Remove IPA characters (ɪ, ɛ, ə, æ, etc.) and use capital letters, dashes, or apostrophes to force pronunciation. Example: 'Mitrex' → 'mih-TREKS'." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "description": "Up to 500 rules.", "type": "array", "items": { "type": "object" } } }, "required": [ "rules" ] }, "example": { "rules": [ { "term": "Mitrex", "pronounceAs": "mih-TREKS", "type": "alias" } ] } } } } } }, "/api/agents/{id}/pronunciation/copy-from/{sourceAgentId}": { "post": { "operationId": "copy-pronunciation", "summary": "Copy rules from another agent", "description": "Replaces this agent's rules with the source agent's, then syncs. Takes no body.", "tags": [ "Pronunciation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The destination agentId." }, { "name": "sourceAgentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agent to copy from." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Copied.", "content": { "application/json": { "example": { "success": true, "rules": [] } } } } } } }, "/api/agents/{agentId}/data-collection/fields": { "get": { "operationId": "list-fields", "summary": "List collection fields", "description": "The only agent endpoint that is public — it sits above the auth middleware so the widget and worker can read it without a key.", "tags": [ "Data collection fields" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." } ], "responses": { "200": { "description": "The fields, in display order.", "content": { "application/json": { "example": { "success": true, "data": { "fields": [] } } } } } } }, "post": { "operationId": "add-field", "summary": "Add a field", "description": "Attaches an existing template to the agent.", "tags": [ "Data collection fields" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "201": { "description": "Added.", "content": { "application/json": { "example": { "success": true, "data": { "field": {} } } } } }, "404": { "description": "The template does not exist.", "content": { "application/json": { "example": { "success": false, "error": "Template not found" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "description": "An existing data collection template.", "type": "string" }, "required": { "description": "Whether the agent must obtain it.", "type": "boolean" }, "customConfig": { "description": "Per-agent overrides of the template.", "type": "object" }, "maxPromptAttempts": { "description": "How many times to ask before giving up.", "type": "number" }, "noResponseBehavior": { "description": "What to do when the visitor will not answer.", "type": "string" }, "triggerCondition": { "description": "When to ask.", "type": "string" }, "order": { "description": "Display and ask order.", "type": "number" } }, "required": [ "templateId" ] }, "example": { "templateId": "tmpl_email", "required": true, "maxPromptAttempts": 2 } } } } } }, "/api/agents/{agentId}/data-collection/fields/reorder": { "put": { "operationId": "reorder-fields", "summary": "Reorder fields", "description": "Send the field ids in the order you want them asked.", "tags": [ "Data collection fields" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Reordered.", "content": { "application/json": { "example": { "success": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fieldIds": { "description": "Ordered field ids.", "type": "array", "items": { "type": "string" } } }, "required": [ "fieldIds" ] }, "example": { "fieldIds": [ "fld_2", "fld_1" ] } } } } } }, "/api/agents/{agentId}/data-collection/fields/{fieldId}": { "put": { "operationId": "update-field", "summary": "Update a field", "description": "Partial update of one field's configuration.", "tags": [ "Data collection fields" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The fieldId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Updated.", "content": { "application/json": { "example": { "success": true, "data": { "field": {} } } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "required": false } } } } }, "delete": { "operationId": "delete-field", "summary": "Remove a field", "description": "Detaches the field from the agent. The underlying template is untouched.", "tags": [ "Data collection fields" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agentId." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The fieldId." }, { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Scopes the request to one workspace." } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "example": { "success": true } } } } } } } } }