Menu
POST canvas-ai/create/ Service tier

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)

KeyRequiredDefault
descriptionoptional or conditionalnone
nameoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "name": "...",
  "status": "...",
  "space_id": "...",
  "url": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400actor_required
400name is required message
400space_id is required message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/create/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "...",
  "name": "...",
  "space_id": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_create)

POST canvas-ai/node-types/ Service tier

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/

Responses

200 bare JSON object (no envelope)

{
  "node_types": [
    {
      "node_type": "...",
      "label": "...",
      "category": "...",
      "scope": "...",
      "description": "..."
    }
  ],
  "count": 0,
  "active_connectors": [
    "..."
  ],
  "sections": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/node-types/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_node_types)

POST canvas-ai/{automation_id}/add-node/ Service tier

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

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
labeloptional or conditionalnone
node_typeoptional or conditionalnone
positionoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "node": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400node_type is required message
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/add-node/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "label": "...",
  "node_type": "...",
  "position": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_add_node)

POST canvas-ai/{automation_id}/configure-node/ Service tier

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

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
labeloptional or conditionalnone
mergeoptional or conditionaltrue
node_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "node": "...",
  "warning": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400node_id is required message
400required_keys_removed
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/configure-node/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "label": "...",
  "merge": true,
  "node_id": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_configure_node)

POST canvas-ai/{automation_id}/connect/ Service tier

Connect two nodes. Body: {source, target, sourceHandle?, targetHandle?, label?}.

URL

  • Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/connect/

Path parameters

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
labeloptional or conditionalnone
sourceoptional or conditionalnone
sourceHandleoptional or conditionalnone
targetoptional or conditionalnone
targetHandleoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "edge": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400cannot connect a node to itself message
400source and target node ids are required message
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/connect/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "...",
  "source": "...",
  "sourceHandle": "...",
  "target": "...",
  "targetHandle": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_connect)

POST canvas-ai/{automation_id}/delete-node/ Service tier

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

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
node_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "node_id": "...",
  "removed_edge_ids": [
    "..."
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400node_id is required message
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/delete-node/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "node_id": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_delete_node)

GETPOST canvas-ai/{automation_id}/graph/ Service tier

Return the current nodes + edges of an automation (canvas shape).

URL

  • Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/graph/

Path parameters

NameType
automation_iduuid

Responses

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "name": "...",
  "status": "...",
  "nodes": [
    "..."
  ],
  "edges": [
    "..."
  ]
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404automation not found message

Example

curl -X GET "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/graph/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_get_graph)

POST canvas-ai/{automation_id}/reposition-node/ Service tier

Move a node. Body: {node_id, x, y}.

URL

  • Service tierhttps://automations.mattering.io/api/internal/canvas-ai/{automation_id}/reposition-node/

Path parameters

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
node_idoptional or conditionalnone
xoptional or conditionalnone
yoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "automation_id": "...",
  "node": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400node_id is required message
400x and y must be numbers message
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/reposition-node/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "node_id": "...",
  "x": "...",
  "y": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_reposition_node)

POST canvas-ai/{automation_id}/run/ Service tier

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

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
proposal_idoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "success": true,
  "started": true,
  "automation_id": "...",
  "proposal_id": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400actor_required
400empty_automation
404automation not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/run/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "proposal_id": "...",
  "space_id": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_run)

GETPOST canvas-ai/{automation_id}/runs/ Service tier

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

NameType
automation_iduuid

Responses

200 bare 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).

Errors

StatusCode
404automation not found message

Example

curl -X GET "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/runs/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_runs)

POST canvas-ai/{automation_id}/stop-run/ Service tier

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

NameType
automation_iduuid

Body keys (JSON)

KeyRequiredDefault
execution_idoptional or conditionalnone
space_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
404automation not found message
404run not found message

Example

curl -X POST "https://automations.mattering.io/api/internal/canvas-ai/AUTOMATION_ID/stop-run/" \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "execution_id": "...",
  "space_id": "..."
}'

Source: AutomationsCore/canvas_ai_views.py (canvas_ai_views.canvas_ai_stop_run)

All Automations resources
Start Free Explore our Products