{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Flows","projectTitle":"Frontline Documentation","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"flows","__idx":0},"children":["Flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flow"]}," is a conversation graph that belongs to a single ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/agents"},"children":["Agent"]},". It defines how the agent reacts to user input: which questions to ask, which AI behavior to run, which external API to call, which conditions to branch on."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flows are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["agent-scoped"]},". They are not reusable across agents — clone or recreate them if you need a similar shape elsewhere."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity","__idx":1},"children":["Identity"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flowId"]}," in nested routes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["enum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DRAFT"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAUSED"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ARCHIVED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runCount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total executions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assistantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Owning agent (always returned in detail)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isDefault"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One flow per agent is the default entry point."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["liveSnapshotId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MongoDB ObjectId of the published snapshot."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["draftSnapshotId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ObjectId of the working draft."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO timestamp."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-graph","__idx":2},"children":["The graph"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A flow's behavior lives in its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["graph"]},": a set of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nodes"]}," connected by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["edges"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"node-types","__idx":3},"children":["Node types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entry point. Every flow has exactly one."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRIGGER_INTENT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Branches the conversation when an Intent matches."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SAY_AI"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sends a message. Optionally generated by the AI model."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESPONSE_AI"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Captures the user's free-text answer guided by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instructions"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOOLS_AI"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lets the AI decide which custom Tool to call (incl. table tools)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Calls an external HTTP endpoint and stores the result."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONDITIONAL_ROUTING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Branches based on AI-evaluated conditions over the context."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATE_RECORD_ACTIVITY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logs a manual activity (note, call, meeting, email, WhatsApp) on a specific Object record."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DYNAMIC_TABLES"]}," (\"Data Action\") node is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["automation-only"]}," and is not available in flows. To read/write records inside a flow, use a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOOLS_AI"]}," node with table tools."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each node has a stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nodeId"]}," (regex ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[a-zA-Z0-9_-]+_\\d+"]},"), an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alias"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["position"]}," for the canvas, and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," payload whose shape depends on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"edges","__idx":4},"children":["Edges"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Edges connect a node's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handle"]}," (output port) to another node's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["targetEdge"]}," (input). The same edge object lives both inline on the node and as a global list — the API normalizes both on write."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reference validation"]},": on create/update, the API validates every cross-resource reference inside a node's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," payload — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentIds"]}," (TRIGGER_INTENT), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customToolIds"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["playbookIds"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["selectedRecordTypes[].id"]}," (TOOLS_AI), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assistantId"]}," (RESPONSE_AI), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aiModelId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["knowledgeBaseIds"]},", etc. If any referenced id does not exist or does not belong to your account, the request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 bad_request"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.issues[].code === \"not_found\""]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no partial state is persisted"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/errors#example-node-references"},"children":["Errors"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"snapshots","__idx":5},"children":["Snapshots"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you publish a flow, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["draft snapshot"]}," is promoted to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["live snapshot"]},". The agent serves traffic from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["liveSnapshotId"]},". Mutations via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /nodes"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /nodes/{nodeId}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /edges"]},", etc. write to the draft."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-start-flow--triggering","__idx":6},"children":["The Start flow & triggering"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default Start flow."]}," Every agent ships with a default flow named ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"Start\""]}," (in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DRAFT"]},") containing a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}," node. It runs ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["automatically at the beginning of every conversation"]}," — first-contact logic (greeting, capturing data, creating a record) belongs here, added after the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}," node. It's the flow with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isDefault: true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}," node is unique."]}," Only the default Start flow may contain a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}," node; the API rejects a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["START"]}," node in any other flow with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Other flows are triggered."]}," A non-default flow begins with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRIGGER_INTENT"]}," node and is entered when it matches the user, configured by either:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Intents"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentIds"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRIGGER_INTENT"]}," node; the flow fires when the user's message matches one of them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Agentic routing"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agenticRouting"]},", a natural-language instruction describing when to enter the flow; the agent routes based on it and the user's intention."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default-message rule."]}," If a flow finishes a turn without producing a user-facing message (e.g. it only captured variables or ran a Dynamic Tables action), the agent sends a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["default AI-generated message"]}," so the user always receives a reply. This applies to every flow."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"variable-interpolation","__idx":7},"children":["Variable interpolation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Text fields can reference variables as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{VARIABLE_NAME}"]},". The name must match exactly (case-sensitive). Interpolable fields include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API node: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers[].value"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameters[].value"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Say AI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prompt"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response AI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instructions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tools AI: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["instructions"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Conditional Routing: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conditions[].expression"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Dynamic Tables: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rowId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rowData"]}," values."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create Record Activity: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rowId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/flow-variables"},"children":["Flow Variables"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"capturing-values-into-variables","__idx":8},"children":["Capturing values into variables"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Interpolation ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["reads"]}," a variable; capturing ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["writes"]}," one. The field that populates a variable depends on the node type:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Node"},"children":["Node"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Item shape"},"children":["Item shape"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tools AI / Response AI / AI Capture"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captureVariables"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference an existing variable"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["variables"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ key, value, fullResponse }"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}," names an existing variable, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is a path into the JSON response"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capture targets must reference a variable that already exists."]}," Create it first (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /agents/{agentId}/variables"]}," for flows, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /workflows/{workflowId}/variables"]}," for automations). In ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captureVariables"]}," you may pass just ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"name\": \"<var>\" }"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"id\": <id> }"]},") — the API resolves it and stores the canonical ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ id, name, description }"]}," so it is linked and rendered in the app. An unknown name/id (or an API ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["variables[].key"]}," that doesn't exist) returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Captured values are matched by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["name"]},", so an AI node and an API node can write to the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{name}"]},". The two node families use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["different fields"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captureVariables"]}," vs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["variables"]},"); the wrong field on a node is silently ignored."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-node-response-paths--value-","__idx":9},"children":["API node response paths (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For an API node, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["property path"]}," into the parsed JSON response — simple property access, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," JSONPath (no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$"]},", wildcards, or filters):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Dot notation for nested objects: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.user.email"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[n]"]}," for array indices: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.items[0].id"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[0]"]}," is equivalent to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".0"]},"; a leading dot is optional)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fullResponse: true"]},", captures the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["whole"]}," response body."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"data\":{\"items\":[{\"id\":42,\"price\":9.99}],\"total\":1}}"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Captured"},"children":["Captured"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.total"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.items[0].id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["42"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.items[0].price"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["9.99"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Path extraction only applies when the response body is JSON. If a step in the path is missing or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", the variable is left unset (no error). Captured objects/arrays are stored as a JSON string; primitives as their string value."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create_record_activity-node","__idx":10},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATE_RECORD_ACTIVITY"]}," node"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logs a manual activity on a specific Object record during a conversation flow."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"nodeId\": \"node_create_activity_1\",\n    \"type\": \"CREATE_RECORD_ACTIVITY\",\n    \"position\": { \"positionX\": 640, \"positionY\": 0 },\n    \"data\": {\n        \"type\": \"CREATE_RECORD_ACTIVITY\",\n        \"recordTypeId\": 5,\n        \"rowId\": \"{contact_row_id}\",\n        \"activityType\": \"NOTE\",\n        \"content\": \"El usuario preguntó sobre: {user_question}\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recordTypeId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Numeric id of the Object's record type. Validated: must exist in your account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rowId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MongoDB ObjectId of the record. Supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{varName}"]}," interpolation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOTE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EMAIL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PHONE_CALL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MEETING"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WHATSAPP"]},". Validated at save time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activity body text. Supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{varName}"]}," interpolation."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Variables in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rowId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," must exist — the API returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," if any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{varName}"]}," is unknown."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operations","__idx":11},"children":["Operations"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Verb"},"children":["Verb"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path"},"children":["Path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List flows"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Detail (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?includeNodes=true"]}," for nodes)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update metadata / status"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Soft delete"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/graph"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full graph (nodes + edges)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/nodes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create node"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/nodes/{nodeId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update node"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/nodes/{nodeId}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete node + incident edges"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/edges"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add/replace edge"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/v1/agents/{agentId}/flows/{flowId}/edges"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove edge"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cli","__idx":12},"children":["CLI"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"frontline agents flows list --table\nfrontline agents flows create --name \"Order Routing\"\nfrontline agents flows nodes create --data '{\"nodeId\":\"start_1\",\"type\":\"START\",\"position\":{\"positionX\":0,\"positionY\":0}}'\nfrontline agents flows edges add --source start_1 --source-handle default --target say_1 --target-handle default\n","lang":"bash"},"children":[]}]},"headings":[{"value":"Flows","id":"flows","depth":1},{"value":"Identity","id":"identity","depth":2},{"value":"The graph","id":"the-graph","depth":2},{"value":"Node types","id":"node-types","depth":3},{"value":"Edges","id":"edges","depth":3},{"value":"Snapshots","id":"snapshots","depth":3},{"value":"The Start flow & triggering","id":"the-start-flow--triggering","depth":2},{"value":"Variable interpolation","id":"variable-interpolation","depth":2},{"value":"Capturing values into variables","id":"capturing-values-into-variables","depth":2},{"value":"API node response paths ( value )","id":"api-node-response-paths--value-","depth":3},{"value":"CREATE_RECORD_ACTIVITY node","id":"create_record_activity-node","depth":3},{"value":"Operations","id":"operations","depth":2},{"value":"CLI","id":"cli","depth":2}],"frontmatter":{"seo":{"title":"Flows"}},"lastModified":"2026-06-05T04:52:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/concepts/flows","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}