{ "info": { "name": "Speak Agent API", "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.\n\nSet the apiKey and workspaceId collection variables before sending anything.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "http://localhost:3001", "type": "string" }, { "key": "apiKey", "value": "sk_live_replace_me", "type": "string" }, { "key": "workspaceId", "value": "replace_me", "type": "string" }, { "key": "agentId", "value": "replace_me", "type": "string" }, { "key": "runId", "value": "replace_me", "type": "string" }, { "key": "resourceId", "value": "replace_me", "type": "string" }, { "key": "fieldId", "value": "replace_me", "type": "string" } ], "item": [ { "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.", "item": [ { "name": "List the workspaces your key can reach", "request": { "method": "GET", "header": [], "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.", "url": { "raw": "{{baseUrl}}/api/org", "host": [ "{{baseUrl}}" ], "path": [ "api", "org" ] } }, "response": [ { "name": "200 — Workspaces the key's user belongs to.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"workspaces\": [\n {\n \"orgId\": \"a1013f16-7149-4f28-b190-c51a0fd29ed5\",\n \"name\": \"Acme Workspace\",\n \"slug\": \"acme-workspace\",\n \"ownerId\": \"bbf36313-fad0-498d-b965-427568726d3d\",\n \"members\": [\n {\n \"userId\": \"bbf36313-fad0-498d-b965-427568726d3d\",\n \"email\": \"you@example.com\",\n \"role\": \"owner\",\n \"joinedAt\": \"2026-02-26T15:54:56.496Z\"\n }\n ],\n \"myRole\": \"owner\",\n \"agentCount\": 2\n }\n ]\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "name": "Agents", "description": "Create, read, update, publish, and delete agents.", "item": [ { "name": "List agents", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "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.", "url": { "raw": "{{baseUrl}}/api/agents", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents" ] } }, "response": [ { "name": "200 — Agents, newest first.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"agents\": [\n {\n \"agentId\": \"e666809a-65c6-4c58-9690-19b3d83e7133\",\n \"name\": \"Nimbus from Nimbus Labs\",\n \"status\": \"active\",\n \"orgId\": \"a1013f16-7149-4f28-b190-c51a0fd29ed5\",\n \"userId\": \"bbf36313-fad0-498d-b965-427568726d3d\",\n \"conversationMode\": \"voice\"\n }\n ]\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Get one agent", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Returns the full agent document. Draft agents automatically include their generation state; add ?include=generation to force it on an active agent.", "url": { "raw": "{{baseUrl}}/api/agents/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id" ], "query": [ { "key": "include", "value": "", "disabled": true, "description": "Set to generation to attach the AI generation record." } ] } }, "response": [ { "name": "200 — The agent.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"agent\": {\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\",\n \"name\": \"Docs Probe\",\n \"status\": \"active\"\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — No such agent in scope.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Agent not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Create an agent", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "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.", "url": { "raw": "{{baseUrl}}/api/agents", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Support Agent\",\n \"personality\": \"friendly and concise\",\n \"instructions\": \"Answer billing questions. Escalate refunds to a human.\",\n \"voice\": {\n \"provider\": \"elevenlabs\",\n \"voiceId\": \"21m00Tcm4TlvDq8ikWAM\"\n },\n \"llm\": {\n \"provider\": \"openai\",\n \"model\": \"gpt-5.4\"\n },\n \"chatSettings\": {\n \"welcomeMessage\": \"Hi, how can I help?\",\n \"maxResponseLength\": 30,\n \"language\": \"en-US\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 — Created. The response contains the fully defaulted agent.", "code": 201, "status": "201", "body": "{\n \"success\": true,\n \"agent\": {\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\",\n \"name\": \"Support Agent\",\n \"personality\": \"friendly and concise\",\n \"instructions\": \"Answer billing questions. Escalate refunds to a human.\",\n \"status\": \"active\",\n \"conversationMode\": \"voice\",\n \"creativityLevel\": 0.5,\n \"stt\": {\n \"provider\": \"deepgram\",\n \"model\": \"nova-3\",\n \"lexiconTerms\": []\n },\n \"voice\": {\n \"provider\": \"elevenlabs\",\n \"voiceId\": \"21m00Tcm4TlvDq8ikWAM\",\n \"pronunciationSyncFailed\": false\n },\n \"llm\": {\n \"provider\": \"openai\",\n \"model\": \"gpt-5.4\"\n },\n \"chatSettings\": {\n \"welcomeMessage\": \"Hi, how can I help?\",\n \"conversationStarters\": [],\n \"topicsToAvoid\": [],\n \"maxSessionLength\": 3,\n \"language\": \"en-US\",\n \"maxResponseLength\": 30\n },\n \"shareSettings\": {\n \"isPublic\": false,\n \"allowedDomains\": []\n },\n \"isDeleted\": false,\n \"createdAt\": \"2026-07-24T19:37:36.742Z\"\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "500 — X-Workspace-Id was missing.", "code": 500, "status": "500", "body": "{\n \"success\": false,\n \"error\": \"Failed to create agent\",\n \"message\": \"Agent validation failed: orgId: Org ID is required\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Update an agent", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Partial update at the top level: fields you omit are left alone. Nested objects are the trap — everything except voice is replaced wholesale.", "url": { "raw": "{{baseUrl}}/api/agents/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Support Agent v2\",\n \"creativityLevel\": 0.8,\n \"voice.voiceId\": \"NEW_VOICE_ID\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — The updated agent.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"agent\": {\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\",\n \"name\": \"Support Agent v2\",\n \"creativityLevel\": 0.8\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "400 — A validation error the server considers user-facing, such as a phone number already assigned to another agent.", "code": 400, "status": "400", "body": "{\n \"success\": false,\n \"error\": \"Phone number is already assigned to another agent\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — No such agent in scope.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Agent not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Save draft changes", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "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.", "url": { "raw": "{{baseUrl}}/api/agents/:id/save-draft", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "save-draft" ] }, "body": { "mode": "raw", "raw": "{\n \"personality\": \"calm and concise\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — The saved agent.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"agent\": {\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\"\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Publish an agent", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Moves the agent to active so it can take conversations. Takes no body. Publishing an already-active agent is harmless.", "url": { "raw": "{{baseUrl}}/api/agents/:id/publish", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "publish" ] } }, "response": [ { "name": "200 — The published agent.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"agent\": {\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\",\n \"status\": \"active\"\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — Not found or not publishable.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Agent not found or not ready to publish\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Delete an agent", "request": { "method": "DELETE", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Soft delete. The document stays in the database with isDeleted true and a deletedAt timestamp, and disappears from every read.", "url": { "raw": "{{baseUrl}}/api/agents/:id", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id" ] } }, "response": [ { "name": "200 — Deleted.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"message\": \"Agent deleted successfully\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — Already deleted, or never existed.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Agent not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "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.", "item": [ { "name": "Get the test suite", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Returns null when the agent has no suite yet, with a 200 rather than a 404.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/suite", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "suite" ] } }, "response": [ { "name": "200 — The suite, or null.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"suite\": null\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "403 — The agent belongs to a different workspace.", "code": 403, "status": "403", "body": "{\n \"success\": false,\n \"error\": \"Forbidden\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Create or replace the test suite", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "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.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/suite", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "suite" ] }, "body": { "mode": "raw", "raw": "{\n \"scenarios\": [\n {\n \"scenarioId\": \"greeting-1\",\n \"name\": \"Greets the caller\",\n \"description\": \"Agent should greet and offer help\",\n \"userMessages\": [\n \"Hi there\"\n ],\n \"criteria\": [\n {\n \"criterionId\": \"c1\",\n \"name\": \"Greeting present\",\n \"evaluationPrompt\": \"Did the agent greet the user and offer help?\",\n \"weight\": 5,\n \"isCritical\": true,\n \"type\": \"llm_judged\"\n }\n ],\n \"category\": \"greeting\",\n \"isEnabled\": true\n }\n ],\n \"maxCostPerRun\": 1,\n \"autoRunOnKbUpdate\": false,\n \"autoRunOnInstructionSave\": false,\n \"scheduledCron\": null\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — The saved suite.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"suite\": {\n \"suiteId\": \"7ea03962-42a9-4e0a-b382-9030a5b1d895\",\n \"agentId\": \"3f5e236b-204f-4ae1-bb93-02ba694e636a\",\n \"orgId\": \"a1013f16-7149-4f28-b190-c51a0fd29ed5\",\n \"scenarios\": [\n {\n \"scenarioId\": \"greeting-1\",\n \"name\": \"Greets the caller\",\n \"isEnabled\": true,\n \"category\": \"greeting\"\n }\n ],\n \"maxCostPerRun\": 1,\n \"autoRunOnKbUpdate\": false,\n \"autoRunOnInstructionSave\": false,\n \"scheduledCron\": null\n }\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "400 — Validation failed. The message names the offending path.", "code": 400, "status": "400", "body": "{\n \"success\": false,\n \"error\": \"\\\"scenarios[0].userMessages\\\" must contain at least 1 items\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Generate a default suite", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "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.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/suite/generate", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "suite", "generate" ] } }, "response": [ { "name": "200 — The generated suite.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"suite\": {\n \"suiteId\": \"7ea03962-42a9-4e0a-b382-9030a5b1d895\",\n \"scenarios\": []\n }\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Start a test run", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Creates the run and returns immediately; scenarios execute in the background. This spends credits and calls your configured model and voice providers.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/run", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "run" ] } }, "response": [ { "name": "200 — The run record, already in progress.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"runId\": \"…\",\n \"status\": \"running\",\n \"trigger\": \"manual\"\n }\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — The agent has no suite.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"No test suite configured\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "409 — A run is already active, credits are insufficient, or no scenario is enabled.", "code": 409, "status": "409", "body": "{\n \"success\": false,\n \"error\": \"Insufficient credits\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Get the active run", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Returns the running or paused run, or null when nothing is in flight.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/run/active", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "run", "active" ] } }, "response": [ { "name": "200 — The active run, or null.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"run\": null\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Pause a run", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Stops after the current scenario finishes. Takes no body.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/run/:runId/pause", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "run", ":runId", "pause" ] } }, "response": [ { "name": "200 — Paused.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — No such run in this workspace.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Run not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Resume a run", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Continues a paused run from where it stopped. Takes no body.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/run/:runId/resume", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "run", ":runId", "resume" ] } }, "response": [ { "name": "200 — Resumed.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Cancel a run", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Ends the run permanently. Scenarios already scored keep their results. Takes no body.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/run/:runId/cancel", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "run", ":runId", "cancel" ] } }, "response": [ { "name": "200 — Cancelled.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "List past runs", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Newest first.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/runs", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "runs" ], "query": [ { "key": "limit", "value": "", "disabled": true, "description": "Defaults to 20, capped at 100." } ] } }, "response": [ { "name": "200 — The runs.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"runs\": []\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Get one run in full", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Includes per-scenario results, per-criterion scores, and any recommendations produced by the run.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/runs/:runId", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "runs", ":runId" ] } }, "response": [ { "name": "200 — The run.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"runId\": \"…\",\n \"status\": \"completed\",\n \"overallScore\": 86\n }\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — No such run in this workspace.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Run not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Apply a recommendation", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Writes a run's suggested fix into the agent configuration. Takes no body. This mutates the agent.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/runs/:runId/recommendations/:recId/apply", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "runs", ":runId", "recommendations", ":recId", "apply" ] } }, "response": [ { "name": "200 — Applied.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {}\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "400 — The recommendation carries no actionable fix.", "code": 400, "status": "400", "body": "{\n \"success\": false,\n \"error\": \"Recommendation has no suggested fix\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — Run or recommendation not found.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Recommendation not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Get the baseline", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "The reference snapshot later runs are compared against. Null until a baseline is set.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/baseline", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "baseline" ] } }, "response": [ { "name": "200 — The baseline, or null.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"baseline\": null\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Get score history", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Flattened points for charting: runId, score, timestamp, and what triggered the run.", "url": { "raw": "{{baseUrl}}/api/testing/:agentId/score-history", "host": [ "{{baseUrl}}" ], "path": [ "api", "testing", ":agentId", "score-history" ] } }, "response": [ { "name": "200 — The history.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"history\": [\n {\n \"runId\": \"…\",\n \"score\": 86,\n \"timestamp\": \"2026-07-24T19:38:48.792Z\",\n \"trigger\": \"manual\"\n }\n ]\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "name": "Agent resources", "description": "Links and documents the agent can surface during a conversation. All of these require X-Workspace-Id.", "item": [ { "name": "List resources", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Paginated, with optional text search.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/resources", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "resources" ], "query": [ { "key": "page", "value": "", "disabled": true, "description": "Defaults to 1." }, { "key": "limit", "value": "", "disabled": true, "description": "1 to 100. Defaults to 10." }, { "key": "search", "value": "", "disabled": true, "description": "Free-text filter." } ] } }, "response": [ { "name": "200 — The resources.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"resources\": [],\n \"total\": 0,\n \"page\": 1,\n \"limit\": 10\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Add a resource", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "All four of url, title, description, and action are required.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/resources", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "resources" ] }, "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/pricing\",\n \"title\": \"Pricing page\",\n \"description\": \"Current plans and prices\",\n \"action\": \"link\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 — Created.", "code": 201, "status": "201", "body": "{\n \"success\": true,\n \"data\": {\n \"resource\": {\n \"resourceId\": \"…\"\n }\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Add resources in bulk", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Between 1 and 100 resources per call, each with the same field rules as a single create.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/resources/bulk", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "resources", "bulk" ] }, "body": { "mode": "raw", "raw": "{\n \"resources\": [\n {\n \"url\": \"https://example.com/docs\",\n \"title\": \"Docs\",\n \"description\": \"Product documentation\",\n \"action\": \"link\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 — Created.", "code": 201, "status": "201", "body": "{\n \"success\": true,\n \"data\": {\n \"created\": 1\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Update a resource", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Send at least one field. All fields are optional individually.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/resources/:resourceId", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "resources", ":resourceId" ] }, "body": { "mode": "raw", "raw": "{\n \"title\": \"Pricing (2026)\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — Updated.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"resource\": {}\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Delete a resource", "request": { "method": "DELETE", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Soft delete, same as agents.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/resources/:resourceId", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "resources", ":resourceId" ] } }, "response": [ { "name": "200 — Deleted.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "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.", "item": [ { "name": "Create or update the share link", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "description": "Returns a long-lived share token plus a short code and a ready-made widget URL.", "url": { "raw": "{{baseUrl}}/api/agents/:id/share", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "share" ] }, "body": { "mode": "raw", "raw": "{\n \"isPublic\": true,\n \"allowedDomains\": [\n \"example.com\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — The share details.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"shareToken\": \"b5a4a9bc11e6ff2f40e70448ecc0f9e153f5d283416dbfd663a4b134cd424a8e\",\n \"shareLink\": \"https://agents.speakai.co/widget/nkqOg5iJtU\",\n \"shortCode\": \"nkqOg5iJtU\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Revoke the share link", "request": { "method": "DELETE", "header": [], "description": "Invalidates the token and short code immediately.", "url": { "raw": "{{baseUrl}}/api/agents/:id/share", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "share" ] } }, "response": [ { "name": "200 — Revoked.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Update widget appearance", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "description": "Partial update of shareSettings.widgetConfig. Returns a message rather than the agent.", "url": { "raw": "{{baseUrl}}/api/agents/:id/widget-config", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "widget-config" ] }, "body": { "mode": "raw", "raw": "{\n \"theme\": \"dark\",\n \"position\": \"bottom-left\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — Updated.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"message\": \"Widget config updated successfully\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "name": "Pronunciation", "description": "Teach the agent how to say brand names and jargon. Rules sync to ElevenLabs when that is the configured voice provider.", "item": [ { "name": "Get pronunciation rules", "request": { "method": "GET", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Returns the rules and the ElevenLabs sync state. syncStatus is not_applicable when the agent does not use ElevenLabs.", "url": { "raw": "{{baseUrl}}/api/agents/:id/pronunciation", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "pronunciation" ] } }, "response": [ { "name": "200 — Rules and sync state.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"rules\": [],\n \"elevenLabsDictId\": null,\n \"elevenLabsVersionId\": null,\n \"syncedAt\": null,\n \"syncStatus\": \"not_applicable\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Replace pronunciation rules", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "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.", "url": { "raw": "{{baseUrl}}/api/agents/:id/pronunciation", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "pronunciation" ] }, "body": { "mode": "raw", "raw": "{\n \"rules\": [\n {\n \"term\": \"Mitrex\",\n \"pronounceAs\": \"mih-TREKS\",\n \"type\": \"alias\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — Saved and synced.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"rules\": [\n {\n \"term\": \"Mitrex\",\n \"pronounceAs\": \"mih-TREKS\"\n }\n ]\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "400 — IPA characters were found in an alias rule.", "code": 400, "status": "400", "body": "{\n \"success\": false,\n \"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'.\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Copy rules from another agent", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Replaces this agent's rules with the source agent's, then syncs. Takes no body.", "url": { "raw": "{{baseUrl}}/api/agents/:id/pronunciation/copy-from/:sourceAgentId", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":id", "pronunciation", "copy-from", ":sourceAgentId" ] } }, "response": [ { "name": "200 — Copied.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"rules\": []\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] }, { "name": "Data collection fields", "description": "Fields the agent gathers during a conversation. Fields are instances of a shared template.", "item": [ { "name": "List collection fields", "request": { "method": "GET", "header": [], "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.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/data-collection/fields", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "data-collection", "fields" ] } }, "response": [ { "name": "200 — The fields, in display order.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"fields\": []\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Add a field", "request": { "method": "POST", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Attaches an existing template to the agent.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/data-collection/fields", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "data-collection", "fields" ] }, "body": { "mode": "raw", "raw": "{\n \"templateId\": \"tmpl_email\",\n \"required\": true,\n \"maxPromptAttempts\": 2\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 — Added.", "code": 201, "status": "201", "body": "{\n \"success\": true,\n \"data\": {\n \"field\": {}\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] }, { "name": "404 — The template does not exist.", "code": 404, "status": "404", "body": "{\n \"success\": false,\n \"error\": \"Template not found\"\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Reorder fields", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Send the field ids in the order you want them asked.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/data-collection/fields/reorder", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "data-collection", "fields", "reorder" ] }, "body": { "mode": "raw", "raw": "{\n \"fieldIds\": [\n \"fld_2\",\n \"fld_1\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — Reordered.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Update a field", "request": { "method": "PUT", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" }, { "key": "Content-Type", "value": "application/json" } ], "description": "Partial update of one field's configuration.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/data-collection/fields/:fieldId", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "data-collection", "fields", ":fieldId" ] }, "body": { "mode": "raw", "raw": "{\n \"required\": false\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 — Updated.", "code": 200, "status": "200", "body": "{\n \"success\": true,\n \"data\": {\n \"field\": {}\n }\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] }, { "name": "Remove a field", "request": { "method": "DELETE", "header": [ { "key": "X-Workspace-Id", "value": "{{workspaceId}}" } ], "description": "Detaches the field from the agent. The underlying template is untouched.", "url": { "raw": "{{baseUrl}}/api/agents/:agentId/data-collection/fields/:fieldId", "host": [ "{{baseUrl}}" ], "path": [ "api", "agents", ":agentId", "data-collection", "fields", ":fieldId" ] } }, "response": [ { "name": "200 — Removed.", "code": 200, "status": "200", "body": "{\n \"success\": true\n}", "header": [ { "key": "Content-Type", "value": "application/json" } ] } ] } ] } ] }