Menu

Node execution

2 endpoints in the Mattering Automations API.

POST node-exec/ Service tier

POST /api/internal/node-exec/: execute a single node function.

Body: {
    node_type: str,           # e.g. "action_slack_send_message"
    capability_name: str,     # alternative: "exec_slack_send_message"
    space_id: str,
    config: dict,             # node config
    org_id: str,              # optional, falls back to header
    describe: bool,           # true returns return the node's config schema, run nothing
    max_chars: int,           # optional cap on the serialized result size
}

Returns the node handler's output directly. An unknown node_type answers 400 with suggestions (closest registered names). When the registry declares required config keys, a config missing them answers 400 missing_config BEFORE any credit is metered.

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/node-exec/

Body keys (JSON)

KeyRequiredDefault
allowed_connector_node_typesoptional or conditionalnone
allowed_connector_slugsoptional or conditionalnone
capability_nameoptional or conditionalnone
configoptional or conditional{}
describeoptional or conditionalnone
execution_payloadoptional or conditionalnone
max_charsoptional or conditionalnone
node_typeoptional or conditionalnone
org_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)

...

200 bare JSON object (no envelope)

{
  "node": "...",
  "executed": false
}

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

Errors

StatusCode
400missing_config
400node_type or capability_name is required message
400org_context_required
402credits_exhausted
403connector_node_not_allowed
403connector_not_allowed

Example

curl -X POST "https://automations.mattering.io/api/internal/node-exec/" \
  -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 '{
  "allowed_connector_node_types": "...",
  "allowed_connector_slugs": "...",
  "capability_name": "...",
  "config": {},
  "describe": "...",
  "execution_payload": "...",
  "max_chars": "...",
  "node_type": "..."
}'

Source: AutomationsCore/agent_bridge_views.py (agent_bridge_views.node_exec)

POST node-exec/ User API

POST /api/user/v1/node-exec/: execute a single QUERY node.

Body: {
    node_type: str,       # e.g. "query_gsc_search_analytics"
    config: dict,         # node-specific configuration
    workspace_id: str,    # optional; space/workspace context for
                          # credential scoping (accepts space_id too)
}

Returns the node handler's output directly (same envelope as the internal node-exec door). Non-query node types are refused with 403 read_only_surface: this door is for pulling data, not for acting.

URL

  • User APIhttps://automations.mattering.io/api/user/v1/node-exec/

Responses

200 bare JSON object (no envelope)

...

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

Errors

StatusCode
400invalid_config
400invalid_json
400node_type_required
400org_context_required
400unknown_node_type
402credits_exhausted
403read_only_surface

Example

curl -X POST "https://automations.mattering.io/api/user/v1/node-exec/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: AutomationsCore/user_api_views.py (user_api_views.user_node_exec)

All Automations resources
Start Free Explore our Products