Create a draft automation. Body: {space_id, name, description?}.
This read is not paginated. It returns at most 2000 rows and does not report a total, so a result of exactly 2000 may be truncated.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/create/
Body keys (JSON)
Key
Required
Default
description
optional or conditional
none
name
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Return the node types the AI may place, filtered by active connectors.
Body (or query string): space_id? (informational; connector gating is org-scoped), category (trigger|action|query|control_flow|utility), connector_slug, q (node_type / label / description contains), view=flat or sections=0 to omit the grouped palette sections (they repeat every node a second time), full=1 for untrimmed descriptions (clipped to ~120 chars otherwise).
This read is not paginated. It returns at most 117 rows and does not report a total, so a result of exactly 117 may be truncated.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/node-types/
Create a node. Body: {node_type, label?, position?{x,y}, config?}.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/add-node/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
label
optional or conditional
none
node_type
optional or conditional
none
position
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Update a node's config/label. Body: {node_id, config?, label?, merge?}.
merge (default true) shallow-merges config into the existing config: a nested object sent replaces that whole object. merge="deep" merges nested objects key by key (null removes a key), so one nested value such as defaults.custom_fields.outreach-status can change alone. merge=false replaces the config wholesale, and is refused when it would drop a key the node type marks required. The answer states changed_keys and removed_keys (dotted paths), so a wipe shows in the same result.
This read is not paginated. It returns at most 10 rows and does not report a total, so a result of exactly 10 may be truncated.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/configure-node/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
config
optional or conditional
none
label
optional or conditional
none
merge
optional or conditional
true
node_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Connect two nodes. Body: {source, target, sourceHandle?, targetHandle?, label?}.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/connect/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
label
optional or conditional
none
source
optional or conditional
none
sourceHandle
optional or conditional
none
target
optional or conditional
none
targetHandle
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Delete a node and its connected edges. Body: {node_id}.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/delete-node/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
node_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/reposition-node/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
node_id
optional or conditional
none
x
optional or conditional
none
y
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Start a run as the acting person. Body: {space_id, proposal_id?}.
Only Agents' run card calls this, after the person pressed Run; the run goes on a worker thread (trigger_views._fire_automation_async, as event triggers do) and is read back through canvas_ai_runs by proposal_id.
This read is not paginated. It returns at most 40 rows and does not report a total, so a result of exactly 40 may be truncated.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/run/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
proposal_id
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Recent runs, and one run in detail. Query/body: execution_id?, proposal_id? (the run a card started), space_id?.
This read is not paginated. It returns at most 10 rows and does not report a total, so a result of exactly 10 may be truncated.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/runs/
Path parameters
Name
Type
automation_id
uuid
Responses
200bare JSON object (no envelope)
{
"automation_id": "...",
"name": "...",
"status": "...",
"runs": [
{
"id": "...",
"status": "...",
"state": "...",
"trigger_type": "...",
"started_at": "2026-01-01T00:00:00Z",
"finished_at": "2026-01-01T00:00:00Z",
"proposal_id": "...",
"error_message": "..."
}
],
"run": null,
"note": "That run has not started yet, or it is not this automation's."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Stop a running run at the next step boundary. Body: {execution_id, space_id?}.
URL
Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/stop-run/
Path parameters
Name
Type
automation_id
uuid
Body keys (JSON)
Key
Required
Default
execution_id
optional or conditional
none
space_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"stopped": false,
"status": "...",
"detail": "That run has already finished."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.