# Automations

> The Automations operations of the Hub REST API (7 operations).

URL: https://docs.synap.live/docs/reference/hub-api/automations · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## POST /automations/create

Create an automation

Creates an automation. Defaults to status=draft. Use POST /automations/{id}/activate to enable it.

Request body (`application/json`): CreateAutomationRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  |  |
| `agentUserId` | string |  |  |
| `workspaceId` | string \| null |  |  |
| `sourceMessageId` | string |  |  |
| `name` | string | yes |  |
| `description` | string |  |  |
| `triggerType` | AutomationTriggerType | yes |  |
| `triggerConfig` | object |  |  |
| `flowDefinition` | FlowDefinition | yes |  |
| `status` | AutomationStatus |  |  |
| `metadata` | object |  |  |

Responses:

- `200`: Created automation
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /automations

List automations

Returns automations for the user, optionally filtered by status.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `userId` | query | string | yes |  |
| `workspaceId` | query | string |  |  |
| `status` | query | AutomationStatus |  |  |
| `limit` | query | string |  |  |

Responses:

- `200`: Array of automations
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /automations/{automationId}

Get an automation

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `automationId` | path | string | yes |  |
| `userId` | query | string | yes |  |
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Automation
- `400`: Bad request
- `403`: Forbidden
- `404`: Automation not found
- `500`: Internal error

## PATCH /automations/{automationId}

Update an automation

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `automationId` | path | string | yes |  |

Request body (`application/json`): UpdateAutomationRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  |  |
| `workspaceId` | string | yes |  |
| `name` | string |  |  |
| `description` | string |  |  |
| `triggerType` | AutomationTriggerType |  |  |
| `triggerConfig` | object |  |  |
| `flowDefinition` | FlowDefinition |  |  |
| `status` | AutomationStatus |  |  |
| `metadata` | object |  |  |

Responses:

- `200`: Updated automation
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /automations/{automationId}/trigger

Manually trigger an automation

Runs the automation flow once with an optional payload. Bypasses the automation's normal trigger config.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `automationId` | path | string | yes |  |

Request body (`application/json`): TriggerAutomationRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  |  |
| `agentUserId` | string |  | Explicit agent user ID when an AI agent asks for the run — routes through the governance gate. |
| `reasoning` | string |  | AI reasoning surfaced on the proposal card. |
| `workspaceId` | string \| null |  |  |
| `payload` | object |  | Optional payload passed to the flow's first node. |

Responses:

- `200`: Trigger result (run id, status, optional output)
- `400`: Bad request
- `403`: Forbidden
- `404`: Automation not found
- `500`: Internal error

## POST /automations/{automationId}/activate

Activate an automation

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `automationId` | path | string | yes |  |

Request body (`application/json`): AutomationLifecycleRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  |  |
| `workspaceId` | string | yes |  |

Responses:

- `200`: Activated automation
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /automations/{automationId}/pause

Pause an automation

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `automationId` | path | string | yes |  |

Request body (`application/json`): AutomationLifecycleRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  |  |
| `workspaceId` | string | yes |  |

Responses:

- `200`: Paused automation
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error