AI Workflow

Return the AI Workflow V2 workflows with status, whether they are live and their version.

Returns the tenant workflows (newest change first) with name, status (DRAFT, PUBLISHED or ARCHIVED), whether the rollout switch is on, the published version and the draft node count. The graph itself is left out so a page stays small; call ai.workflows.get for one workflow with its graph. Use it to find the workflow id for any other ai.workflows.* tool. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Create a new workflow as a DRAFT. It answers no customer until published and rolled out.

Creates a workflow with status DRAFT and rollout off. It is not live and answers no customer: going live takes ai.workflows.publish and ai.workflows.rollout (both ai:manage). Send the graph as draftGraph. Use ai.workflows.validate to check it afterwards. Writes one row and sends nothing. Answers 201 with the created workflow.

Return which workflow is the default for one channel account, and why.

Resolves the workflow that answers customers on one channel account: the workflow bound to that account, else the account-wide default, else the latest enabled published one. The answer names the source of the choice. Use it before ai.workflows.setDefault to see what would be replaced. Answers 404 when no published workflow can answer. Read-only.

Return whether the AI is on for one channel account and which workflow it uses.

Returns for one channel account: whether the AI answers customers there (enabled), the workflow bound to it (workflowId and the source of that choice) and the account-wide default workflow id. Use it to answer "is the bot on for this number?" before ai.workflows.setChannelState. Read-only.

Switch the AI on or off for one channel account.

Turns the AI on or off for one channel account (one phone number, Instagram account, page, bot or widget). This changes what customers are answered with, immediately, on live conversations. enabled:false stops the bot from answering new customer messages on that account, so they wait for a human; enabled:true lets the bot reply again. It does not send a message itself and does not change which workflow is bound (that is ai.workflows.setDefault, ai:manage). Use ai.workflows.channelState first to see the current state. The change is immediate and reversible by calling this again.

Return one workflow with its draft graph, trigger configuration and publish state.

Returns the workflow row including draftGraph: every node with its configuration, which can contain the system prompts and instructions the AI answers with. Treat the content as the tenant's business logic. The draft may be ahead of the live version; publishedVersion tells which version is live. Read-only.

Change the name, description or draft graph. The live version is not touched.

Updates the draft side of a workflow. A published workflow keeps answering customers from its last published version: the runtime never reads the draft, so an edit here changes nothing for customers until ai.workflows.publish (ai:manage) snapshots it. Send only the fields to change. Forged outbound write approvals in the graph are stripped. Writes one row and sends nothing. Validate afterwards with ai.workflows.validate.

Return the most recent runs of one workflow, optionally for one conversation.

Returns the latest runs (at most the 120 most recent) of one workflow with status, step reached, channel, conversation and customer name. Use it to see how a workflow behaved on real conversations; follow up with ai.traces.get for the step-level detail. For runs across all workflows use ai.executions.list. Read-only. Paginated within those 120 rows: follow meta.pagination.nextCursor until hasMore is false.

Return the published version history with a node-count summary of each.

Returns each published version (newest first) with when it was published and a summary: node count, edge count, start node and node types. The graphs themselves are left out; use ai.workflows.export for the current graph. Use it to see how many times a workflow went live and what changed in size. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return the workflow as a portable document that ai.workflows.import accepts.

Returns the workflow in the import format: name, description, trigger configuration and draft graph, with outbound connection ids stripped so the document is portable. Use it to copy a workflow, to back one up, or to read a graph in the shape the editing tools expect. The content includes the AI prompts of the workflow. Read-only.

Dry-run an import document and report its shape, or why it is rejected.

Parses a workflow import document and answers valid:true with the node and edge counts, or a 400 naming what is wrong. Nothing is stored. Use it before ai.workflows.import, so a rejected document costs no clean-up.

Check the draft graph for errors and warnings without changing anything.

Runs the graph validator on the stored draft and returns valid plus the list of issues (code, message, node id, severity). Use it after ai.workflows.update and before ai.workflows.publish: publishing refuses a draft with blocking issues. Nothing is saved or sent. Answers 400 when the workflow has no draft graph yet.

Create a DRAFT workflow from an import document.

Creates a new workflow with status DRAFT from a document in the export format. It is not live and answers no customer until it is published and rolled out (ai:manage). Outbound references in the document are re-resolved against this tenant. Run ai.workflows.validateImport first. Writes one row and sends nothing. Answers 201.

Snapshot the draft as a new live version of the workflow.

Validates the draft and, when it is clean, stores it as the next published version and marks the workflow PUBLISHED. This changes what customers are answered with, immediately, on live conversations. If this workflow already answers customers, the next customer message is answered by the new version. Publishing is refused when the draft has blocking validation issues or references an unavailable outbound resource; outbound write approvals are never granted here. Run ai.workflows.validate first. A version cannot be edited afterwards; publish again to change it.

Retire a workflow: it is switched off and stops answering customers.

Marks the workflow ARCHIVED and turns its rollout off. This changes what customers are answered with, immediately, on live conversations. A workflow that was answering customers stops; if it was the default for a channel, that channel falls back to another published workflow or to no AI answer. There is no public tool to un-archive it. The workflow and its history are kept (it is not deleted).

Enable or disable a published workflow for live traffic.

Sets the rollout switch of one workflow. This changes what customers are answered with, immediately, on live conversations. enabled:true makes the published version eligible to answer customers (refused with 400 if the workflow was never published); enabled:false takes it out of rotation. Other workflows are unaffected. For one channel only, use ai.workflows.setChannelState instead.

Bind a published workflow to one channel account as the one that answers.

Binds the workflow to one channel account so it becomes the one that answers customers there, replacing the previous binding. This changes what customers are answered with, immediately, on live conversations. The workflow must be published. To bind several accounts at once use ai.workflows.applyDefaultAll. Check the current choice with ai.workflows.default first.

Bind a published workflow to up to 50 channel accounts in one call.

Binds the workflow to every listed channel account, replacing each previous binding. This changes what customers are answered with, immediately, on live conversations. It affects every account listed, so list only the accounts that should switch. The workflow must be published. Use ai.workflows.setDefault for a single account.

Return AI workflow runs across all workflows, newest first, with their outcome.

Returns the runs of the AI (one per customer message it handled) with workflow, status, channel, conversation, customer name, the customer message that triggered it, the step reached and safety counters. Use it to audit what the AI did or to find failed runs; ai.traces.get gives the step-by-step detail of one. The prompt-builder and agent summaries in each row can quote the prompt content. Read-only and rate-limited to 20 calls per minute. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return how many runs and signals the safety checks blocked or sent to review.

Returns four counters over the matching runs: executions that raised a safety signal, the total signals, how many were blocked and how many went to review. It scans every matching run, so narrow it with from and to. Use it for a quick safety health read instead of paging ai.executions.list. Read-only and rate-limited to 20 calls per minute.

Return one row per conversation with its run count, status mix and latest runs.

Groups the AI runs by conversation: each row has the customer, channel, how many runs the conversation had, a count per status, safety counters and a preview of the latest runs. Use it to review how the AI handled whole conversations rather than single runs. Read-only and rate-limited to 20 calls per minute. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return one run with its status, timing, safety counters and agent summary.

Returns one run: status, workflow and version, conversation, the customer message that started it, retry count, safety counters and the prompt-builder and agent summaries. The summaries can quote prompt content. For the individual steps use ai.traces.get. Read-only.

Return every step the AI took in one run, with redacted inputs and outputs.

Returns the step-level trace of one run: each event with its type, status, error, and the redacted input and output of the step. This can include the prompts sent to the model, retrieved knowledge text and the customer's own words, so handle it as sensitive. At most 200 steps are returned; meta.truncated says whether more existed. Use it to find out why a run failed or answered badly. Read-only and rate-limited to 20 calls per minute.

Return the intent, sentiment, confidence and routing the AI decided per message.

Returns the decision signals the AI recorded for one conversation, newest first: detected intent, sentiment, buying stage, churn risk, confidence band, whether it routed to a human or asked a clarifying question. Use it to see why the AI escalated or stayed silent. Returns at most limit rows and has no further pages. Read-only.

Return intent match rate, fallback rate, handover precision and approval load.

Aggregates the recorded AI decision signals over a window of days into total signals, labelled signals, intent match rate, fallback rate, handover precision and approval load. Use it to judge whether the decision policy needs tuning before ai.decision.setPolicy. Read-only and rate-limited to 20 calls per minute.

Return a heuristic summary and suggested next step for one customer conversation.

Builds a conversation summary and suggestion from the customer's recent messages and the knowledge base, with a confidence value. It uses no AI credits (no model call is billed). The id is the customer id from customers.list; an id that is not one of this tenant's customers answers 404. Use it to brief an agent before handing a conversation over. Read-only and rate-limited to 20 calls per minute.

Return handoffs from the AI to a person that are waiting for approval or assigned.

Returns the handoff queue: requests where the AI passed a conversation to a human and that are still PENDING (waiting for approval) or ASSIGNED, with the reason, the customer, the channel and the assignee. Use it to find conversations that need a person, then ai.handoffs.approve or ai.handoffs.cancel for those waiting. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return every handoff recorded for a conversation, newest first.

Returns the history of handoffs for one conversation: when the AI handed it over, why, whether it was approved, cancelled, skipped (no agent was available) or failed, and who it went to. Use status=PENDING to see only the one waiting for approval. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Route a conversation from the AI to a human agent, or queue it for approval.

Creates a handoff and, unless requireApproval is true, immediately picks an agent (from targetAgentIds or targetTeamIds, else any, by distributionMethod) and assigns the conversation to them. The assignee sees it in their inbox and the dashboard gets a realtime update. Nothing is sent to the customer. With requireApproval the handoff stays PENDING until ai.handoffs.approve. The answer is SKIPPED when no agent is available and FAILED when assignment errored; neither assigns anyone. Use assignments.set instead when you already know exactly which person should take it.

Approve a handoff that waits for approval and assign the conversation to an agent.

Approves a PENDING handoff created with requireApproval, picks an agent by the handoff's own targets and assigns the conversation to them. The assignee sees it in their inbox and the dashboard gets a realtime update; the customer is not messaged. Answers 400 if the handoff is no longer PENDING, so it is safe to retry. Use ai.handoffs.pending to find handoffs waiting.

Cancel a handoff that is still waiting, with a reason.

Marks a PENDING handoff CANCELLED and records the reason. Nobody is assigned and nobody is notified; the conversation stays where it was. Only a PENDING handoff can be cancelled, anything else answers 400. Use it when approval will not be given.

Return the documents and text the AI can answer from, with their processing status.

Returns the knowledge sources, most recently changed first: name, type (text, pdf, site), size, how many chunks it was split into, status (ready, syncing or failed with the error) and branchIds (the branches the source is restricted to; [] means every branch). The content itself is left out; ai.knowledge.get returns it. Use it to check that a source finished processing before relying on it. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Add text the AI may answer customers from; it is chunked and embedded in the background.

Stores the text as a knowledge source and queues it for processing (splitting and embedding, which may use AI credits). Once its status is ready, the AI can quote it when answering customers, so only add text that is accurate and fine to repeat to customers. This is the text variant only: file uploads and URL sources are not available here. Send branchIds to let the AI use it only in conversations of those branches (omit it for every branch). Subject to the plan limit on knowledge documents (403 when reached). Answers 201 with status syncing; poll ai.knowledge.get until ready. Rate-limited to 20 calls per minute.

Return one source with its full text and processing status.

Returns the source including its stored text content, the number of chunks, whether it is ready, whether it can be edited with ai.knowledge.update (editable is false for uploaded files that have no stored text) and branchIds (the branches it is restricted to; [] means every branch). Read-only.

Replace the text of an existing source; it is re-chunked and re-embedded.

Replaces the whole content of a text source. The old chunks are removed immediately and the new text is processed in the background (may use AI credits), so for a short while the AI has less to answer from; once status is ready it quotes the new text to customers. Only sources with editable true and a text type can be changed here; an uploaded file or URL source is refused with 400 rather than overwritten. Send the full new content, not a patch. branchIds restricts the source to those branches ([] makes it apply to every branch; omit it to leave the restriction as it is); a request that carries only branchIds changes the restriction and leaves the text, and works for uploaded files too. Rate-limited to 20 calls per minute.

Permanently delete a source and its chunks; the AI stops answering from it.

Deletes the source and all of its chunks permanently. This changes what customers are answered with: the AI can no longer quote it, immediately, in every workflow that retrieves from it. It cannot be undone; the text of a text source can be read with ai.knowledge.get first and re-added with ai.knowledge.create.

List owned website sources with readiness and latest sync state.

List owned website sources with readiness and latest sync state. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Create a bounded public website source and queue its first generation.

Create a bounded public website source and queue its first generation. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Read readiness, active configuration and latest sync state.

Read readiness, active configuration and latest sync state. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Remove a managed source and retire its stored generations.

Remove a managed source and retire its stored generations. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Change desired configuration for the next manual sync.

Change desired configuration for the next manual sync. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Read a bounded page of article metadata from the active generation.

Read a bounded page of article metadata from the active generation. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Queue a manual generation refresh; the previous active version remains usable.

Queue a manual generation refresh; the previous active version remains usable. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Immediately withdraw a source from retrieval and cancel pending work.

Immediately withdraw a source from retrieval and cancel pending work. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Enable a source; run a new successful sync before it becomes ready.

Enable a source; run a new successful sync before it becomes ready. Owner/admin only. Global and tenant Website Knowledge opt-in are required for create, update, sync and enable. Public HTTPS, same-origin bounded ingestion; no login, JavaScript execution, live browsing or automatic refresh. Failed refresh preserves the prior active generation. Managed sources cannot use text-source update, replacement or deletion. Create and sync require a stable requestId; retries replay for 24 hours. Inventory returns items and nextCursor, without article content or worker state.

Return the workspace AI settings, including how long a human takeover holds.

Returns the workspace AI Workflow settings. The one setting today is humanHandoffTtlMinutes: how many minutes a conversation held by a person stays off-limits to the AI before the AI resumes answering; 0 means never, the person must resolve or unassign it. The first read creates the default row if none exists. Otherwise read-only.

Set how long a human takeover holds before the AI resumes.

Sets humanHandoffTtlMinutes, the number of minutes a conversation assigned to a person is kept away from the AI. After that time the assignment is released and the AI answers the customer's next message again. This changes what customers are answered with, immediately, on live conversations. A small value makes the AI take back conversations people are still handling; 0 (the default) never releases them. Applies to every conversation in the workspace. Read the current value with ai.settings.get first.

Return the saved system prompts with their active version and persona.

Returns the tenant system-prompt library (plus the built-in default): name, the active text, the persona it uses and the latest and active version numbers. AI agent nodes reference these by id. The text is the instruction the AI answers customers with. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Add a new system prompt to the library. Nothing uses it until a workflow references it.

Adds a system prompt (up to 50 per workspace) as version 1. A new prompt is not referenced by any workflow node, so it changes no customer answer until a workflow draft that uses it is published. Writes the prompt and its first version, sends nothing. Answers 201. To change an existing prompt use ai.settings.systemPromptUpdate.

Return every stored version of one system prompt with its change note.

Returns the version history of one system prompt, newest first: version number, the full text at that version, who saved it and the change note. Use it to see what an edit changed. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return the saved personas the AI can speak as.

Returns the persona library: name, description, the persona text (tone and role instructions) and which one is the default. Prompts and follow-up rules reference personas by id. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Add a new persona to the library. Nothing uses it until a prompt or rule references it.

Adds a persona (up to 50 per workspace). A new persona is not the default and is not referenced by anything, so it changes no customer answer until a system prompt or follow-up rule is pointed at it. Writes one row and sends nothing. Answers 201. To change an existing persona use ai.settings.personaUpdate.

Change the name, description or text of an existing persona.

Edits a persona in place. This changes what customers are answered with, immediately, on live conversations. Prompts and follow-up rules that reference the persona use the new text from their next run, with no publish step and no version history. Send only the fields to change. Read the current text with ai.settings.personas first so it can be restored.

Save a new active version of a system prompt.

Stores the change as a new version and makes it the active one at once. This changes what customers are answered with, immediately, on live conversations. Every workflow node that references this prompt uses the new text from its next run: there is no publish step. The previous text stays in the version history (ai.settings.systemPromptVersions) so it can be copied back. Send only the fields to change; add a changeNote saying why.

Return the metadata of the tools a workflow can give the AI.

Returns the registry of AI tools (name, what each does, its input shape, whether it reads or writes). Use it to know which capabilities a workflow node can enable when drafting with ai.workflows.update. Static metadata, not the tenant's configuration. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return the thresholds and rules that decide when the AI answers, asks or hands over.

Returns the decision policy: confidence thresholds per band, intent overrides, clarification prompts, persona mapping, prompt-injection keywords and scoring weights. Pass workflowId for a workflow-specific policy; without it the workspace policy (or the built-in default) is returned. Read-only.

Merge changes into the workspace or one workflow decision policy.

Merges the policy fields you send into the stored policy (fields you omit keep their value). This changes what customers are answered with, immediately, on live conversations. Lower confidence thresholds make the AI answer more and escalate less; higher ones the reverse. With workflowId the change applies to that workflow only. Read the current policy with ai.decision.policy and judge the effect with ai.decision.evaluation first.

Run the decision engine on a message and return intent, sentiment and routing.

Runs the full decision pipeline on one message text and returns the envelope: detected intent, sentiment, confidence, buying stage, churn risk, whether it would answer, ask a clarifying question or hand over, and any retrieved knowledge. It sends nothing to the customer and starts no workflow, but it is not free of side effects: it searches the knowledge base (which may use credits) and records a decision signal against the conversationId, which then appears in ai.conversations.signals and in ai.decision.evaluation. Use a conversationId you do not mind annotating. Rate-limited to 20 calls per minute.

Return the Custom API and Remote MCP connections the AI can call, without credentials.

Returns each outbound connection a workflow can use: kind, name, base URL, status, whether a credential is stored (never the credential, nor any part of it) and how many operations or tools are active. Use it to know which external systems the AI may reach. Connections cannot be created or changed through the API. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return each web widget with its allowed origins and whether the AI answers on it.

Returns the web chat widgets: name, whether enabled, the origins allowed to embed it and the AI state (which workflow answers and whether the AI is on). The embed key and snippet are left out. Use the widget id as channelAccountId in ai.workflows.channelState. Change one with ai.webWidgets.update. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return one web widget with its allowed origins and AI state.

Returns one web chat widget: name, enabled, allowed origins and AI state. The embed key and snippet are left out. Read-only.

Rename a web widget, switch it on or off, or change the sites allowed to embed it.

Changes only the fields you send. allowedOrigins replaces the whole list: each entry is an origin (scheme and host, optional port, no path; https://*.example.com allows subdomains), normalised and de-duplicated, at most 20. An entry that is not an origin is refused rather than dropped. A site missing from the list can no longer open the widget and enabled false stops it answering visitors, both at once on live conversations. Read the current list with ai.webWidgets.get first so it can be restored. The embed key, theme and pre-chat form cannot be changed here, and widgets cannot be created, rotated or deleted through the API.

Open a simulator conversation for trying a workflow.

Creates a playground session with a simulated customer (a tagged contact that is never a real customer) and returns its id and empty transcript. It calls no model and spends no credits. Pass the id as sessionId to ai.playground.run to keep a multi-message conversation; without a session each run starts a fresh one. Every session gets its own simulator contact, so parallel sessions never share memory. Writes the session and the simulator contact; sends nothing. Answers 201.

Send one simulated customer message through a workflow and return what the AI answered.

Runs the workflow on a simulated customer message and returns the AI reply, the run status and the transcript so far; it waits up to 25 seconds for the reply. When the run is still going the status is running: read the reply with ai.playground.result using the returned sessionId and executionId. This calls the real AI model and so SPENDS AI CREDITS on every call. It is not sent to anyone: the customer is a simulator contact and calls to external APIs that would write are only described. Use it to test a published workflow before ai.workflows.rollout, or to see what the AI would answer from the knowledge base. The status is blocked when no published workflow is selected. Pass sessionId to continue a conversation. Rate-limited to 5 calls per minute.