Operations

Returns the authenticated user's identity, active org context, and org settings (company description, brand standards).

Returns a product overview and a lightweight list of all entity types. Use info:entity for detailed information about a specific entity type.

Returns detailed information about a specific entity type: full description and relationships.

Discover available operations and their input/output schemas. Call with no target to list all ops, each with the tool it is called through. Call with a target op name to get the JSON Schema for that op's input and output. For entity ops, provide entityType to get the entity-specific params schema.

Create a new empty edit session with the given name. Returns the session ID.

Duplicate an existing edit session under a new name: the new session starts with a copy of all staged changes, and the source session is left untouched. Returns the new session ID.

Get a session by ID, including all tracked entities and their current state.

List all active edit sessions.

Run full validation on the session: entity local validation, cross-entity global checks, and cascade rules.

Validate and save all session changes to the database in a single transaction. Supports dryRun mode to check validation and version conflicts without persisting. On success, the session is destroyed. Get your user's go-ahead before saving — asked in product terms (what the chatbot will now do, e.g. "I'll make the greeting live on your homepage — ok?"), never as internals: no 'session', 'save', op names, or ids in front of them.

Discard an edit session, throwing away all unsaved changes.

Get a summary of all changes in the session: created, updated, and deleted entities, including cascade changes. Updated entities include a diff of field-level changes (add/remove/replace/move ops) from the persisted baseline.

Create a new entity in the session. The system generates the ID. Returns the new entity ID and any validation errors.

Get a single entity by type and ID. Without a sessionId, loads from the database. With a sessionId, includes unsaved changes. Some types accept an alternate selector via params instead of entityId: wikiPage takes { path: "folder-slug/page-slug" }, wikiFolder takes { slug }.

List entities by type. Without a sessionId, lists saved entities from the database. With a sessionId, includes unsaved changes. wikiPage rows are metadata summaries (path, folder, title, summary, keywords, section headings) without content — use entity:get for the full page, and filter with { folder: "folder-slug" }.

Update an entity in the session. Provide only the fields you want to change. Auto-loads from the database if not already in the session. Returns the change diff (same op format as session:diff) and validation errors; call entity:get when you need the full normalized entity.

Mark an entity for deletion in the session. The entity will be deleted from the database when the session is saved.

Reload an entity from the database into the session, returning the fresh state and the agent's previous pending changes. Use after a save conflict.

Append one item to a keyed collection without resending the whole array. path is a dotted path ending on the array (e.g. "goals" or "goals.support.instructions"). Provide the new item in item; omit its key to have it derived from the name. Pass afterKey to insert directly after an existing member instead of appending. Returns the change diff and validation errors.

Remove one item from a keyed collection without resending the whole array. path is a dotted path ending on the member (e.g. "goals.support" or "goals.support.instructions.intro"). Returns the change diff and validation errors; emptying a collection that requires members surfaces as a localError rather than failing.

Shallow-merge a patch into one item of a keyed collection without resending the whole array. path is a dotted path ending on the member (e.g. "goals.support"). Only the fields in patch change; the member keeps its key (do not rename a key — it orphans bound data). Reconciling cross-member invariants is the caller's responsibility. Returns the change diff and validation errors.

Move one item of a keyed collection to a new position without resending the whole array — only meaningful for ordered collections. path is a dotted path ending on the member (e.g. "instructions.pricing"); afterKey is the key of the member to place it directly after, or null to move it to the front. Returns the change diff and validation errors.

Get a workflow by ID.

List all workflows for the org. Optionally filter by workflowType (workflow, tool, chatbot, card).

Create a new workflow in the session. workflowType is immutable after creation: "workflow" runs on events, "tool" is invoked as a chatbot/agent tool, "chatbot" runs for chatbots that assign it (assign via the chatbot's workflowIds), "card" is owned by a card definition and runs at display time to fetch its props (the card_instance_created trigger). When omitted, it is inferred from the definition's trigger (chatbot_tool/tool → "tool", card_instance_created → "card", otherwise "workflow"). The chatbot_tool and tool triggers are only allowed on tool-type workflows, and tool-type workflows allow no other triggers. Declare caller-supplied parameters (tool args, a card's fetch args) as inputFields on the definition's trigger — or add them later with workflow:updateNode. A definition with unknown input keys (any inputs key not declared by the node type) or inputFields on a trigger that takes no caller inputs is rejected. While the workflow is disabled (the default status), localErrors covers only structural checks; full {{ref}} validation runs once it is enabled, at session save, or on demand via workflow:validate.

Update workflow fields (name, status, definition, variables). variables are static constants ({{variables.key}}); caller-supplied parameters live in the trigger's inputFields (set via workflow:updateNode on the trigger node). A definition with unknown input keys is rejected.

Delete a workflow from the session.

Execute a workflow by ID. Pass input values matching the inputFields declared on the workflow's trigger (undeclared keys are rejected — runtime callers only supply declared fields). This is a test invocation, so visitorId/threadId are generated for you when you omit them from triggerPayload — pass them only to target a specific visitor or thread. With a sessionId, the run resolves session-staged entities (an unsaved connector, workflow edits) — no need to save the session just to test. Returns the full execution trace with per-step inputs, outputs, errors, timing, and the workflow output (if a workflow_output node was reached).

List past runs of a workflow, newest first — one page of summaries (status, version, timestamps, credits spent; no step traces) plus the workflow's current version, so a run with an older workflowVersion executed an outdated definition. Each summary carries its origin: where the run came from (a chatbot conversation, a custom agent's tool call), when it has one. Filter by isTest and statuses; page by passing the returned nextCursor back as cursor. A workflow created in a session and not yet saved lists its runs only with that sessionId (they are test runs — pass isTest true or omit it). Read a run's full trace with workflow:getRun.

Get a past run by ID: the full execution trace (per-step inputs, outputs, errors, timing), what it cost (credits in total and per node) and the workflow definition the run executed — including unsaved edits staged in a session, flagged by ranUncommitted — so you diagnose a run against what actually ran, not the current definition. A run of a workflow created in a session and not yet saved is readable only with that sessionId. A conversation origin means the run happened inside that chatbot conversation — point the user at it via its threadId (the dashboard's conversation view).

List available node definitions for workflows. Optionally filter by kind (trigger, action, control) and/or workflowType (only definitions allowed for that workflow type). Each carries what it costs the workspace to run (charge), absent for a free node.

Get the full definition of a node type. Each input field reports its uiType, whether it's required, options (allowed values for dropdown fields), entityRef (the field takes an id of that entity type — with secretType/acceptedConnections for secret/connection refs), and the raw flag (raw fields skip {{...}} interpolation and ref validation — for script/regex/template bodies). Also returns output fields, sample output and what the node costs the workspace to run (charge; absent for a free node). For triggers, configurableInputFields reports whether the workflow may declare caller-supplied inputFields on its trigger node (distinct from this op's inputFields, which describe the node's own inputs config).

Validate a workflow definition. Returns all validation errors regardless of workflow status.

Add a node after a specified node. Use pathIndex to add it at the start of a specific branch of a paths node or lane of a parallel node. Auto-generates the node name; set the node's inputs with workflow:updateNode.

List cached results, the ones expiring last first (newest first among entries kept for one TTL), a page at a time: each entry's stored input (the key), output, when it was stored and lapses, and the run, workflow and step that stored it. Name them by workflow node (workflowId + nodeName: the entries that node's configured inputs could have stored) or by inputs (nodeType + an optional inputs template in which every {{…}} matches anything — { url: 'https://api.example.com/{{rest}}' } is every request to that host; without a template, every entry of the type, which is shared by node type and inputs across the workspace's workflows). Pass sessionId to read the edit session's cache instead of the live one.

Drop one cached result by its id from workflow:listNodeCache, named by the same node or type. The step runs again on its next call with those inputs.

Drop cached results: by workflow node, those its configured inputs could have stored; by nodeType with an inputs template, those matching it; by nodeType alone, every entry of the type across the workspace's workflows (or the edit session's, with sessionId). Every affected step runs again on its next call.

Remove a node by name from the workflow definition.

Update a node's displayName, inputs or cache setting. On the trigger node, may also set inputFields — the workflow's caller-supplied parameters (read as {{input.*}}), which form the tool input schema for tool workflows and the fetch args for a card's data workflow. inputFields exist only on the trigger — set on any other node they have no effect. inputs keys not declared by the node's type are rejected. cache ({ ttlSeconds }, or null to turn it off) is accepted on cacheable action nodes only (see the workflow entity info); on any other node it fails validation.

Change the trigger type. Resets inputs and updates displayName from the node definition; declared inputFields are kept when the new trigger accepts caller inputs (configurableInputFields) and dropped otherwise. Triggers not allowed for the workflow's workflowType produce a validation error in localErrors.

Replace a node with a different type, preserving its position in the chain.

Add a new branch to a paths node.

Remove a branch from a paths node by index.

Add an empty lane to a parallel node. Fill it with workflow:addNode, passing the parallel node as afterNodeName and the lane's index as pathIndex.

Remove a lane from a parallel node by index, with every node in it.

Update the conditions on a specific path of a paths node. Conditions are ANDed; each is { type: "comparison", firstValue, operator, secondValue } or { type: "fallback" }. Operators: text_equals/text_not_equals/text_contains/text_not_contains/text_starts_with/text_ends_with, text_matches/text_not_matches (a literal RE2 regex, never a reference; unanchored, (?i) for case-insensitive), list_has/list_not_has (an item equals the value) and list_has_match/list_not_has_match (an item matches the regex) on a {{reference}} to a list, number_equals/number_greater/number_less, boolean_is_true/boolean_is_false, exists/not_exists, date_older_than/date_newer_than (durations like 5m, 2h). The info:entity description for workflow has the details.

List all agents for the org. With sessionId, includes unsaved changes.

Get a agent by ID.

Create a new agent in the session. The system generates the ID. Returns the new agent ID and any validation errors.

Update a agent in the session. Provide only the fields you want to change. Tools are object-keyed by name — pass null to delete a tool, or a partial object to patch one.

Mark a agent for deletion in the session.

Send a test message to a agent and get its response. Tests the saved configuration, or pass sessionId to test unsaved draft changes. Invocations are one-shot — no thread or memory is carried across calls.

Send a test message to a chatbot and get its response. The conversation is recorded as a test thread (isTest: true in chat:listThreads), never as a real customer conversation. Tests the chatbot's saved configuration, or pass sessionId to test unsaved draft changes. If threadId is omitted, a new conversation is started. Pass back the returned threadId to continue a multi-turn conversation. Admin callers may pass modelOverride (a model-router string) and providerOptions to benchmark the reply on a different model.

List conversation threads — real customer conversations and test threads. Filter by chatbotId (omit to list across all chatbots), visitorId, isTest (true = test only, false = real only, omit = both), humanTakeover, closed, and createdAt/updatedAt date ranges. Threads where the visitor never sent a message are excluded unless includeThreadsWithNoUserMessages is true; threads judged spam, abuse or gibberish after closing are excluded unless includeSpam is true. Each thread includes the visitor's name and a last-message preview; use chat:getMessages to read a thread.

Get the messages of a conversation thread — real or test. Use this to review what happened in a conversation and debug chatbot behavior.

List the org's tasks (things a user or agent needs to resolve). Defaults to open tasks; pass status to inspect done/dismissed, or kind to filter.

Get one task by ID, including its subtasks and their instructions.

Mark a whole task as done.

Dismiss a task — hide it without acting on it. Use complete when the work was actually done.

Mark one subtask (by its key) done. The task auto-closes once every subtask is resolved.

Mark one subtask (by its key) not-applicable. Counts as resolved for auto-close.

Get the agent-onboarding state for this workspace: whether setup is required before configuration changes are allowed, spec progress per part, and the next action to take.

Get the workspace spec — questions about the customer's company, website, existing interactions, and goals. Parts unlock sequentially; answer the current part via setup:answerSpec. Gather real evidence (browse the site, use browser:* ops, or ask your user) — do not guess.

Answer spec questions. Accepts answers for the current (and earlier) parts only — future parts stay locked until the current one is complete. Once every part is answered, the next step is a build plan (setup:submitPlan).

Record that the user explicitly declined pairing the Algomo browser extension, unblocking the evidence-gated spec parts on fallback evidence. ONLY call this after your user has clearly declined in chat — never to route around the requirement yourself. The reason is recorded verbatim and audited.

Verify the chatbot's website-browsing tools against what the site actually shows — the mandatory finish line of the website-access build task. YOU gather the rendered side: drive the user's paired browser to each page (browser:navigate — tell your user first, you will steer their tab for a minute) and read the rendered text and main-content links (browser:runScript, extraction adapted to the site — SPAs, cookie banners, odd DOM are yours to handle). Submit at least two pages (a listing page and a detail page) with the tool + input that should reproduce each. The server then runs your tool itself and scores the match mechanically: text coverage and item-link coverage. If a page paginates, make sure your tool follows the pages — coverage is scored per page, so completeness beyond page 1 is on you. Iterate until every page passes; the scores are stored and quoted in your final report.

Record that verified website access is not achievable for this site and the user accepts proceeding without it. ONLY call this after your user has explicitly accepted in chat — never to skip verification effort. The reason is recorded verbatim and audited.

Get the current build plan (latest submitted version) and setup progress toward it.

Submit the build plan: the parts you intend to build (title + description each), grounded in the spec answers, plus a searchDecision — sites with search get a search tool by default: 'planned' spawns its own build task (never write search as a plan part), and skipping requires a recorded reason your user has accepted. IMPORTANT: present the plan to your user in chat and get their explicit go-ahead BEFORE submitting. Requires a complete spec. Re-submitting replaces the plan (versions are kept; open build tasks are re-synced). Submitting completes setup, unlocks configuration ops, and spawns one build task per plan part plus fixed messenger-config and test-and-report tasks — work through them via task:list.

List the recipe catalog — capability playbooks with best practices. Read them ALL with recipe:get before planning: setup:submitPlan is blocked until every recipe has been read, because a plan is only as good as your knowledge of what the product can do.

Get a recipe's full playbook (markdown) and, for template recipes, the JSON Schema of recipe:apply's input.

Stage a recipe's template into a session: a known-good, pre-wired starting point (entities created and attached). Read the recipe first (recipe:get) — its input schema and the customization guidance matter. Review what was staged with session:diff and customize it against the workspace spec before saving.

Overview of the browser:* namespace — what a paired browser extension can do and how to drive it. Call this before the other browser ops. While impersonating another org, the response also explains that browser ops act on your own browser under your real org (not the impersonated one).

List the paired browser-extension sessions currently connected for your org, with the owning user and a browser label. Each session is one browser; use browser:listTabs to see its tabs. Returns nothing if no extension is paired and connected.

List a session's tabs that have the extension enabled, with each tab's live current URL and title. Pick a tabId from here for browser:getCaptures, browser:runScript, browser:request, and browser:navigate. Only enabled-origin tabs are listed.

Drain the passively-captured request/response records buffered for a specific tab (return-and-clear — repeated calls don't re-deliver). Defaults to a compact summary: one line per call (method, URL, status, content type, body sizes) — enough to discover which APIs a page uses. Pass include: "full" for bodies (truncated to maxBodyChars, default 2000), and maxRecords to bound the batch. Keep these bounds: a busy page can buffer megabytes, and an oversized result is rejected wholesale — the records are already cleared by then, so they are lost.

Run JavaScript in a specific tab's page context (MAIN world) and return its value. The code is the body of an async function — reference inputs via args, top-level await is allowed, and end with a top-level return of the result (same convention as connector scripts). A script that throws fails the op with the script's error. Only works on enabled-origin tabs.

Replay an HTTP request from inside a specific tab, so it carries that page's cookies (including HttpOnly/SameSite), Origin, and Referer exactly as the app's own calls do — use this to probe the site's APIs. Pass the call to replay as a nested request object ({ url, method, headers, body }); the reply comes back under response (status, headers, body). Only works on enabled-origin tabs.

Navigate a specific tab to a URL and wait for the load to settle, returning the tab's final url and title (so redirects are visible). Both the tab's current origin and the destination origin must be enabled for the extension — you can move a tab around the client's own site(s), but not to arbitrary origins.

Capture a screenshot of a tab's visible viewport (jpeg by default, or png; quality applies to jpeg only). The image is uploaded to short-lived private storage — you get back a presigned image URL valid for about an hour (the object itself is deleted within a day) plus its pixel dimensions. Only enabled-origin tabs can be captured; the extension briefly activates the target tab to take the shot.

Get the org's messenger (chat widget) channel settings. allowedDomains restricts which website domains the widget may open on; an EMPTY list means the widget is allowed on every domain — do not clear the list to disable the widget. title is shown in the widget header and empty state; avatarUrl is the public URL of the uploaded avatar shown on bot messages (null = default icon), scaled within its frame by avatarScale (percent); mainColor is the accent hex behind the trigger bubble, the visitor's message bubbles, and the default avatar; horizontalOffset/bottomOffset inset the trigger bubble from the page's bottom-right corner, in px.

Update the org's messenger (chat widget) channel settings — a partial update; omitted fields keep their current value. allowedDomains, when provided, is the FULL new list (not a patch) of bare domains like example.com — no protocol or path; entries are normalised (lowercase, www stripped) and deduplicated, max 200; an empty list allows the widget on every domain. title (1–80 chars) is shown in the widget header and empty state. avatarUrl is the image shown as the bot avatar: a URL from the avatar upload flow (validated as this org's file) or any other public https image URL, stored as-is; pass null to clear it. avatarScale (25–200 percent, default 100) scales the uploaded avatar image within its frame and avatarBackground (default true) toggles the frame's solid fill behind it — neither affects the default icon. mainColor (hex like #4f46e5, default #091724) is the accent behind the trigger bubble, the visitor's message bubbles, and the default avatar; the widget picks light or dark foreground automatically. horizontalOffset/bottomOffset (0–400 px, default 16) inset the trigger bubble from the page's bottom-right corner. Live op — takes effect immediately, no session/save step.

List the org's third-party connections (OAuth and API key). Returns redacted summaries — no encrypted credentials are exposed. To create, reauthorize, or delete connections, direct the user to https://dash.algomo.com/settings/connections.

Get a single connection by ID. Returns a redacted summary — no encrypted credentials are exposed. Use to look up a connectionId before referencing it from a workflow action input.

List the valid values for a workflow action's connection field. Pass the field's acceptedConnections (from workflow:getNodeDefinition) and receive every option the picker would show: tenant connections plus any 'Algomo managed' built-in options the platform offers for those services. Each option's value is the exact JSON to write into the action's connectionId input — either a user connection ref { type: "user", id, service, tokenType? } or a managed ref { type: "managed", service }. Prefer this op over connection:list when wiring a connection field on a workflow node.

Get a chatbot's website install snippet — the Algomo pixel, which powers the messenger and visitor tracking. The snippet names the chatbot it serves: pages carrying it are handled by this chatbot, while pages with another chatbot's snippet are handled by that one, so a site can point different areas at different chatbots. The default chatbot also serves any page whose snippet names no chatbot. Returns the two ways to install (the site's own HTML, or a Google Tag Manager container) with the exact snippet and placement instructions for each, plus the chatbot's page where the user can copy it themselves. Installing is the go-live step, not a prerequisite for testing — the paired browser extension injects the pixel into your own browser, so a chatbot can be tried on the customer's real site before their site carries the snippet. Prefer sending them the link over pasting the snippet into chat. Read-only: putting it on the site is their change to make.

Build a dashboard link to any app page for your user. target.page names the page and the rest of target its params (see the schema: a chatbot, a workflow's runs tab, a conversation, a wiki page by its folder-slug/page-slug path, the settings pages). Pass sessionId to open the page with that edit session selected, so the user sees the staged changes in place — this is how you show your user what you built before it is saved. Never assemble dashboard URLs yourself.