Automations API & MCP

You can list automations, inspect their details, view run history, and execute macros programmatically — using either the REST API or the UserHero MCP server.

REST API

Base URL: https://userhero.co/api/v1

All endpoints require a Bearer token. Create an API key from Account > API Keys in the dashboard. Read operations require the automations:read scope; creating, updating, deleting, or running automations requires automations:write.

List automations

GET /api/v1/automations?projectId={id}

Returns all automations for a project, ordered by priority.

Query parameters

Response

{
  "automations": [
    {
      "id": "abc123",
      "name": "Auto-assign billing",
      "scope": "feedback.created",
      "enabled": true,
      "priority": 0,
      "conditions": { "combinator": "and", "rules": [] },
      "actions": [{ "type": "assign_agent", "params": { "userId": "..." } }],
      "runStats": { "matched7d": 42, "errored7d": 0 },
      "lastRunAt": "2026-05-30T10:00:00Z"
    }
  ],
  "nextCursor": "def456"
}

When nextCursor is present, pass it as cursor to fetch the next page.

Get a single automation

GET /api/v1/automations/{id}

Returns full automation details including conditions, actions, and statistics.

Run a macro

POST /api/v1/automations/{id}/run

Execute a macro (scope: "manual") against a specific feedback item.

Request body

{ "feedbackId": "feedback_abc123" }

Response

{
  "runId": "run_xyz789",
  "outcome": "matched",
  "actionsExecuted": [
    { "type": "set_status", "success": true },
    { "type": "add_tag", "success": true }
  ]
}

outcome is matched, no-match, or error.

List run history

GET /api/v1/automations/{id}/runs

Returns the last 50 execution runs for an automation, ordered by most recent first.

Response

{
  "runs": [
    {
      "id": "run_xyz789",
      "outcome": "matched",
      "runAt": "2026-05-30T10:00:00Z",
      "feedbackId": "feedback_abc123",
      "actionsExecuted": [{ "type": "set_status", "success": true }]
    }
  ]
}

MCP Tools

If you use the UserHero MCP server, four automation tools are available.

list_automations

List automations for a project with optional filtering.

Parameters

Example prompts:

"List all enabled automations in my project" "Show me all macros in project abc123" "Which automations are currently disabled?"

get_automation

Get full details of a single automation.

Parameters

Returns: Full automation including conditions, actions, statistics, and metadata.

Example prompt:

"Show me the details of automation jg9bTVq5gSvjVm0L55cS"

list_automation_runs

List recent execution runs for an automation.

Parameters

Returns: Array of runs with outcome, timestamp, number of actions executed, and the feedback ID.

Example prompt:

"Show me the last 10 runs of the auto-assign macro" "Did any runs fail for automation abc123?"

run_macro

Execute a macro against a feedback item.

Parameters

Example prompt:

"Run the 'Close and thank' macro on feedback #1370"

See MCP Tools Reference for the full list of available tools.