GET
agents/capabilities/
User API Service tier
GET /api/internal/agents/capabilities/: capabilities available given active connectors.
Returns all productivity capabilities plus any connector-gated capabilities whose connector is active for this org.
URL
User API https://automations.mattering.io/api/user/v1/agents/capabilities/
Service tier https://automations.mattering.io/api/internal/agents/capabilities/
Responses
200 bare JSON object (no envelope)
{
"capabilities": [
{
"name": "...",
"service": "...",
"description": "...",
"category": "...",
"method": "..."
}
],
"active_connectors": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 Missing org context message 500 mattering_capabilities not installed message
Example
User API Service tier
curl -X GET "https://automations.mattering.io/api/user/v1/agents/capabilities/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://automations.mattering.io/api/internal/agents/capabilities/" \
-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/agent_bridge_views.py (agent_bridge_views.list_available_capabilities)
GET
agents/execution/
User API Service tier
GET /api/internal/agents/execution/: get execution status/result.
URL
User API https://automations.mattering.io/api/user/v1/agents/execution/
Service tier https://automations.mattering.io/api/internal/agents/execution/
Query parameters
Name Default
execution_idnone
Responses
200 bare JSON object (no envelope)
{
"execution_id": "...",
"agent_id": "...",
"agent_name": "...",
"status": "...",
"trigger_type": "...",
"output_summary": "...",
"tool_calls": "...",
"error_message": "...",
"total_input_tokens": "...",
"total_output_tokens": "...",
"cost_cents": 0.0,
"started_at": "2026-01-01T00:00:00Z",
"finished_at": "2026-01-01T00:00:00Z"
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 execution_id is required message 404 Execution not found message
Example
User API Service tier
curl -X GET "https://automations.mattering.io/api/user/v1/agents/execution/?execution_id=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://automations.mattering.io/api/internal/agents/execution/?execution_id=..." \
-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/agent_bridge_views.py (agent_bridge_views.get_agent_execution)
GET
agents/export/
Service tier
Full agent-module export for the Matter migration.
Consumed once by Matter's import_automations_agents command (Phase 5 of planning/matter-agents-architecture.md). Secret-gated by the /api/internal/ mount. Read-only; the tables stay for one release as backup after the import.
URL
Service tier https://automations.mattering.io/api/internal/agents/export/
Responses
200 bare JSON object (no envelope)
{
"agents": [
{
"id": "...",
"org_id": "...",
"name": "...",
"description": "...",
"status": "...",
"system_prompt": "...",
"context_template": "...",
"model": "...",
"max_turns": 0,
"created_by": "...",
"capabilities": [
{
"name": "...",
"service": "...",
"constraints": "..."
}
],
"schedules": [
{
"name": "...",
"cron_expression": "...",
"timezone": "...",
"context_template": "...",
"space_id": "...",
"status": "...",
"max_invocations": "..."
}
]
}
],
"count": 0
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
curl -X GET "https://automations.mattering.io/api/internal/agents/export/" \
-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/agent_bridge_views.py (agent_bridge_views.agents_export)
POST
agents/invoke/
User API Service tier
POST /api/internal/agents/invoke/: trigger an agent execution.
Body: {
agent_id: str,
space_id: str,
context: dict, # runtime context for prompt rendering
instructions: str, # user message / task description
}
URL
User API https://automations.mattering.io/api/user/v1/agents/invoke/
Service tier https://automations.mattering.io/api/internal/agents/invoke/
Body keys (JSON)
Key Required Default
agent_idoptional or conditional none configoptional or conditional none contextoptional or conditional none instructionsoptional or conditional none space_idoptional 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
200 bare JSON object (no envelope)
{
"execution_id": "...",
"agent_id": "...",
"agent_name": "...",
"status": "...",
"output_summary": "...",
"tool_calls_count": 0,
"total_input_tokens": "...",
"total_output_tokens": "...",
"cost_cents": 0.0,
"started_at": "2026-01-01T00:00:00Z",
"finished_at": "2026-01-01T00:00:00Z"
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 agent_id is required message 500 Agent execution failed to start message
Example
User API Service tier
curl -X POST "https://automations.mattering.io/api/user/v1/agents/invoke/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "...",
"config": "...",
"context": "...",
"instructions": "...",
"space_id": "..."
}' curl -X POST "https://automations.mattering.io/api/internal/agents/invoke/" \
-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 '{
"agent_id": "...",
"config": "...",
"context": "...",
"instructions": "...",
"space_id": "..."
}'
Source: AutomationsCore/agent_bridge_views.py (agent_bridge_views.invoke_agent)
GET
agents/list/
User API Service tier
GET /api/internal/agents/list/: list agents for a space/org.
URL
User API https://automations.mattering.io/api/user/v1/agents/list/
Service tier https://automations.mattering.io/api/internal/agents/list/
Query parameters
Name Default
workspace_idnone
Responses
200 bare JSON object (no envelope)
{
"agents": [
{
"id": "...",
"workspace_id": "...",
"name": "...",
"description": "...",
"status": "...",
"model": "...",
"max_turns": 0,
"capabilities": [
{
"name": "...",
"service": "...",
"constraints": "..."
}
],
"schedules": [
{
"id": "...",
"name": "...",
"cron": "...",
"status": "...",
"next_fire_at": "2026-01-01T00:00:00Z"
}
],
"created_at": "2026-01-01T00:00:00Z"
}
]
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 Missing org context message
Example
User API Service tier
curl -X GET "https://automations.mattering.io/api/user/v1/agents/list/?workspace_id=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://automations.mattering.io/api/internal/agents/list/?workspace_id=..." \
-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/agent_bridge_views.py (agent_bridge_views.list_agents)