> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulate a conversation > Runs a text or voice simulation against the agent and streams the conversation back as server-sent events. Set draftMode to test unpublished changes without billing. Each event is a turn or tool-call frame, and the stream ends with a done or error event. ## OpenAPI ````yaml /openapi.yaml post /agents/{agentId}/simulate openapi: 3.1.0 info: title: Flowyte V2 Control-Plane REST API version: 1.0.0 description: >- The single REST API for the Flowyte platform (base path `/api/v1`). Authenticate every request with a secret API key — `Authorization: Bearer flowyte_sk_…` — and each operation lists the scope the key must hold. Successful responses use the `ApiResponse` envelope; list responses use cursor-based `PaginatedResponse`. Errors are RFC 9457 problem+json. Streaming endpoints return Server-Sent Events (`event:\ndata:\n\n`, terminating with `event: done`). contact: name: Flowyte Platform license: name: Proprietary servers: - url: /api/v1 description: Flowyte control-plane (versioned URI; additive in v1). security: - apiKey: [] tags: - name: Agents description: The single user-facing entity. - name: Skills description: > Agent capabilities / tools. A skill is ONE atomic action — typically a single API call the agent makes in one step (look up an order, create a record, send a message, transfer the call). Use a skill when the task is a single step. When a task needs several details gathered across turns BEFORE acting, build a Playbook (which gathers the inputs and then calls skills) — see the Playbooks tag. - name: Integrations description: Native OAuth integrations. - name: Knowledge description: RAG knowledge sources & preview. - name: Playbooks description: > Multi-turn conversation scripts — a node graph (gather → confirm → branch) the agent follows to collect several inputs IN ORDER across turns before acting. Build a playbook when a single skill call isn't enough because the agent must gather MANY details first, or run a SEQUENCE of skills, before it can finish (e.g. take a full service request: gather the problem, address, and time, confirm, THEN file it; qualify a lead; a multi-step intake). A playbook does NOT call an integration itself — it owns the conversation and holds the state across turns; the actual action is performed by the SKILL(s) it gathers the inputs for. So a playbook ORCHESTRATES skills. Rule of thumb — one API call → a Skill; "gather N things in order, then submit" → a Playbook that drives the conversation and calls the skill(s) at the end. - name: Variables description: > The agent-wide interaction-variable registry (B.4b) — DERIVED at read time from the agent's playbooks and skills (collect slots, skill output bindings, {var} placeholders) and merged with a thin annotation overlay (notes, declared type hints, manual declarations). Read-only observation, NEVER a gate: it never validates a reference and never affects authoring, publish, or runtime behaviour. - name: Guardrails description: Deterministic guardrail policies & caller verification. - name: Numbers description: Phone numbers / DIDs. - name: Test description: Test, simulate, talk-token, probe. - name: Observe description: Post-call analytics, conversations, receipts, transcripts. - name: Billing description: Plans, wallet, usage, fixed phrases. - name: Voices description: Voice catalog. - name: Webhooks description: Webhook endpoints & deliveries. - name: AuditLogs description: API/key activity logs. - name: Chat description: Chat channel — sessions, messages, OpenAI-compatible, widget. - name: PublishableKeys description: Browser-safe, one-agent publishable keys. - name: Widget description: Embed widget config + snippet. - name: Uploads description: Multipart file uploads backing file_id params - name: Meta description: Platform metadata (language/SKU/tier capabilities). paths: /agents/{agentId}/simulate: parameters: - $ref: '#/components/parameters/AgentIdPathScoped' post: tags: - Test summary: Simulate a conversation description: >- Runs a text or voice simulation against the agent and streams the conversation back as server-sent events. Set draftMode to test unpublished changes without billing. Each event is a turn or tool-call frame, and the stream ends with a done or error event. operationId: simulateAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateRunRequest' responses: '200': description: SSE stream of SimulateEvent. content: text/event-stream: schema: $ref: '#/components/schemas/SimulateEvent' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFound' security: - apiKey: - agents:write components: parameters: AgentIdPathScoped: name: agentId in: path required: true schema: type: string schemas: SimulateRunRequest: type: object required: - mode description: > Chat/voice draft tester request. `mode` selects the tester surface: `text` (in-UI chat tester) or `voice` (in-browser voice draft tester); `voice_browser`/`probe_loopback` also supported. `draftMode` runs the simulation against the ephemerally compiled draft config (default true for the in-builder tester). properties: scenarioId: type: string mode: type: string enum: - text - voice - voice_browser - probe_loopback draftMode: type: boolean description: > Run against the ephemerally-compiled draft config (not the published version, not billed). Default true for the in-builder chat/voice tester. transcript: type: array items: type: string SimulateEvent: description: > The live simulate/chat SSE frame. It IS an AuditEventDTO: the SSE `event:` line equals `eventType` and the `data:` line is the AuditEventDTO JSON. Streams terminate with `event: done` or `event: error`, consumed via fetch() streaming. allOf: - $ref: '#/components/schemas/AuditEventDTO' AuditEventDTO: type: object description: > One audit/simulate event. Persisted as a receipt row (Screen 8) AND emitted verbatim as the SSE frame `data:` on the simulate/chat streams (where the SSE `event:` equals `eventType`). `payload` is the per-eventType shape — see the `*Payload` schemas; the mapping is: user_utterance→UserUtterancePayload, agent_message→AgentMessagePayload, tool_call→ToolCallPayload, kb_retrieval→KbRetrievalPayload, guardrail→GuardrailPayload, verification→VerificationPayload, language_switch→LanguageSwitchPayload, handoff→HandoffPayload, barge_in→BargeInPayload, latency→LatencyPayload, filler→FillerPayload, call_started→CallStartedPayload, call_ended→CallEndedPayload, error→ErrorPayload. required: - id - conversationId - seq - tsMs - channel - eventType - payload properties: id: type: string conversationId: type: string seq: type: integer tsMs: type: integer channel: type: string enum: - voice - chat eventType: $ref: '#/components/schemas/AuditEventType' traceId: type: string payload: description: >- Per-eventType payload (see schema description for the eventType→*Payload mapping). oneOf: - $ref: '#/components/schemas/UserUtterancePayload' - $ref: '#/components/schemas/AgentMessagePayload' - $ref: '#/components/schemas/ToolCallPayload' - $ref: '#/components/schemas/KbRetrievalPayload' - $ref: '#/components/schemas/GuardrailPayload' - $ref: '#/components/schemas/VerificationPayload' - $ref: '#/components/schemas/LanguageSwitchPayload' - $ref: '#/components/schemas/HandoffPayload' - $ref: '#/components/schemas/BargeInPayload' - $ref: '#/components/schemas/LatencyPayload' - $ref: '#/components/schemas/FillerPayload' - $ref: '#/components/schemas/CallStartedPayload' - $ref: '#/components/schemas/CallEndedPayload' - $ref: '#/components/schemas/ErrorPayload' ProblemDetails: description: RFC 9457 problem+json. type: object properties: type: type: string format: uri default: about:blank title: type: string status: type: integer detail: type: string instance: type: string code: type: string errors: type: array items: type: object properties: field: type: string message: type: string ApiResponse_Void: allOf: - $ref: '#/components/schemas/ApiResponseBase' - type: object properties: data: type: - object - 'null' AuditEventType: type: string description: > Authoritative AuditEvent / SimulateEvent event-type set. Each value selects the per-variant payload shape documented on AuditEventDTO.payload (see the *Payload schemas below). The legacy `agent_utterance`/`turn_summary` values are also supported for the ported audit_events write-path. enum: - user_utterance - agent_message - tool_call - kb_retrieval - guardrail - verification - language_switch - handoff - barge_in - latency - filler - call_started - call_ended - error - agent_utterance - turn_summary UserUtterancePayload: type: object required: - text - isFinal properties: text: type: string language: type: string asrConfidence: type: number isFinal: type: boolean AgentMessagePayload: type: object required: - text - format properties: text: type: string language: type: string format: type: string enum: - spoken - markdown quickReplies: type: array items: type: string interrupted: type: boolean ToolCallPayload: type: object required: - skillId - skillName - skillType - args - status properties: skillId: type: string skillName: type: string skillType: type: string args: type: object additionalProperties: true result: type: object additionalProperties: true status: type: string enum: - success - error - blocked durationMs: type: integer error: type: object properties: code: type: string message: type: string KbRetrievalPayload: type: object required: - query - grounded - chunks properties: query: type: string grounded: type: boolean topScore: type: number chunks: type: array items: type: object required: - sourceId - sourceName - score properties: sourceId: type: string sourceName: type: string score: type: number language: type: string snippet: type: string GuardrailPayload: type: object required: - policyType - decision properties: policyType: type: string decision: type: string enum: - allowed - blocked - redacted - escalated field: type: string rule: type: string reason: type: string VerificationPayload: type: object required: - method - status properties: method: type: string enum: - ani - otp - kba - web_session status: type: string enum: - requested - passed - failed attemptsRemaining: type: integer LanguageSwitchPayload: type: object required: - from - to - source properties: from: type: string to: type: string source: type: string enum: - word_level_tags HandoffPayload: type: object required: - target properties: target: type: string enum: - human - subagent - number destination: type: string reason: type: string contextSummary: type: string BargeInPayload: type: object required: - atMs - falseInterruption properties: atMs: type: integer ttsStoppedMs: type: integer falseInterruption: type: boolean LatencyPayload: type: object required: - turnIndex - responseLatencyMs properties: turnIndex: type: integer responseLatencyMs: type: integer components: type: object properties: eouMs: type: integer sttMs: type: integer llmTtftMs: type: integer ttsTtfbMs: type: integer FillerPayload: type: object required: - text properties: text: type: string CallStartedPayload: type: object required: - agentId - draft - primaryLanguage properties: agentId: type: string draft: type: boolean agentVersionId: type: string sku: type: string primaryLanguage: type: string CallEndedPayload: type: object required: - reason - durationS properties: reason: type: string enum: - completed - transferred - caller_hangup - error durationS: type: number goalCompleted: type: boolean ErrorPayload: type: object required: - code - message properties: code: type: string message: type: string stage: type: string ApiResponseBase: type: object required: - success properties: success: type: boolean message: type: string errors: type: array items: type: object required: - field - message properties: field: type: string message: type: string responses: ValidationError: description: Validation failure (errors[] populated on the envelope). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ApiResponse_Void' NotFound: description: Resource not found in org scope. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: apiKey: type: oauth2 description: > Flowyte secret API key (`Authorization: Bearer flowyte_sk_live_…`). Scope-gated; is scoped to your organization — a key can never reach another tenant. The listed scopes in each operation's `apiKey` requirement are the scopes that key must hold. The `tokenUrl` is nominal: keys are minted in the dashboard. flows: clientCredentials: tokenUrl: /api/v1/api-keys scopes: agents:read: Read agents. agents:write: Create/update/delete agents, publish, rollback. knowledge:read: Read knowledge sources & preview. knowledge:write: Add/remove knowledge sources, uploads. skills:read: Read skills & skill-types. skills:write: Create/update/delete skills. playbooks:read: Read playbooks & graphs. playbooks:write: Create/update/delete playbooks & graphs. guardrails:read: Read guardrail policies & caller-verification. guardrails:write: Update guardrail policies & caller-verification. numbers:read: Read phone numbers / search availability. numbers:write: Purchase / assign / release numbers. sms:read: Read the org's SMS (10DLC) registration status and numbers. sms:write: Save/submit the 10DLC registration and toggle numbers for SMS. outbound:read: Read outbound contact lists and campaigns. outbound:write: >- Create/import contact lists, create/launch/pause/resume/cancel outbound campaigns, and enqueue single outbound calls. integrations:read: Read connected native integrations (status only — never tokens). integrations:write: Discover schemas, set data scoping, and disconnect a connection. integrations:connect: >- Connect a data source (submit credentials / begin OAuth) — a SEPARATE, higher-privilege scope because connecting INGESTS credentials and opens a new egress path; a discover/scope/author key need not carry it. calls:read: Read conversations, receipts, transcripts, analytics. analytics:read: >- Read the Observe history list, per-agent analytics (the answer-rate summary), and the raw knowledge-gap list. analytics:write: >- Curate knowledge gaps (dismiss / mark in-progress). [M4 — reserved] billing:read: Read plans, wallet, usage. audit:read: Read API/key activity logs. webhooks:write: Manage webhook endpoints. keys:write: Manage secret API keys. chat:read: Read chat sessions & messages. chat:write: Create chat sessions & send messages (server-side). widgets:read: Read widget config & embed snippet. widgets:write: Update widget config. pubkeys:read: Read publishable keys. pubkeys:write: Manage publishable keys. ````