# Automation

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## POST /automation/start/{automationId}

**Start an automation**

`operationId: AutomationController_startAutomation`

Arms the automation's trigger. From this point it runs **unattended** whenever the trigger fires — sending email, writing records, calling external services and, depending on its actions, moving money.

Validate the definition and check the trigger's selectivity first: a trigger that matches more records than intended runs its actions on all of them.

#### Signature

```http
POST /automation/start/{automationId} (automationId: string, body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Arms unattended, repeating execution.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/ai/validate`
- `POST /automation/stop/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Request body

Optional start options.

```json
{}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/stop/{automationId}

**Stop an automation**

`operationId: AutomationController_stopAutomation`

Disarms the trigger so the automation stops firing. Executions already in flight run to completion — stopping is not a kill switch for work already started.

#### Signature

```http
POST /automation/stop/{automationId} (automationId: string, body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- In-flight executions still finish.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/start/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Request body

Optional stop options.

```json
{}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/status/{automationId}

**Get an automation's status**

`operationId: AutomationController_getAutomationStatus`

Whether an automation is running, when it last fired, and its recent outcome.

#### Signature

```http
GET /automation/status/{automationId} (automationId: string) -> The status
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /automation/execution/history`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The status |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/health

**Get automation health**

`operationId: AutomationController_getHealth`

Whether the automation engine is processing — the check to run when nothing seems to be firing.

#### Signature

```http
GET /automation/health () -> Health
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /automation/dashboard/stats`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Health |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/dashboard/stats

**Get automation statistics**

`operationId: AutomationController_getDashboardStats`

Run counts, success and failure rates across the org's automations.

#### Signature

```http
GET /automation/dashboard/stats () -> Statistics
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /automation/execution/history`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Statistics |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/execution/history

**Get execution history**

`operationId: AutomationController_getExecutionHistory`

Past automation runs and their outcomes — the record for working out why something did or did not happen.

#### Signature

```http
GET /automation/execution/history (automationId?: string, limit?: integer, offset?: integer) -> Executions
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /automation/dashboard/stats`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | query | string | — |  |
| `limit` | query | integer | — |  |
| `offset` | query | integer | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Executions |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation

**List automations**

`operationId: AutomationController_getAutomations`

The org's automations and whether each is running.

#### Signature

```http
GET /automation () -> Automations
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `GET /automation/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Automations |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation

**Create an automation**

`operationId: AutomationController_createAutomation`

Defines an automation — its trigger, conditions and actions. **Created stopped**: it does nothing until started, which is the safe default for a definition that has not been reviewed.

#### Signature

```http
POST /automation (body) -> The automation
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Created inactive.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/start/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The automation.

```json
{
  "name": "Welcome email",
  "trigger": {
    "type": "record.created",
    "datatype": "customer"
  },
  "conditions": [],
  "actions": [
    {
      "type": "send-email",
      "template": "welcome"
    }
  ]
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The automation |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/executions/{executionId}

**Get a run**

`operationId: AutomationController_getRun`

One run: its summary, step results, errors, completed steps and the variables it carried.

#### Signature

```http
GET /automation/executions/{executionId} (executionId: string) -> The run
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `executionId` | path | string | yes | Run id (`exec_…`). |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The run |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Run not found — No run with that executionId. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/executions/{executionId}/cancel

**Stop a run**

`operationId: AutomationController_cancelRun`

Cancels a run that is still going.

#### Signature

```http
POST /automation/executions/{executionId}/cancel (executionId: string) -> { cancelled: true, executionId }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |
| `400` | ALREADY_DONE | This run has already finished — there is nothing to stop. | The run finished or failed ("already failed"). | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `executionId` | path | string | yes | Run id (`exec_…`). |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { cancelled: true, executionId } |
| `400` | This run has already finished — there is nothing to stop. — The run finished or failed ("already failed"). |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Run not found — No run with that executionId. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/executions/{executionId}/retry

**Run it again**

`operationId: AutomationController_retryRun`

Runs the automation again now with the same variables, as a new run linked to this one (`retryOf`). Real effects, like any run.

#### Signature

```http
POST /automation/executions/{executionId}/retry (executionId: string) -> { success, executionId, retryOf, message }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | RUN_NOT_FOUND | Run not found | No run with that executionId. | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `executionId` | path | string | yes | Run id (`exec_…`). |

### Responses

| Status | Meaning |
| --- | --- |
| `201` | { success, executionId, retryOf, message } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Run not found — No run with that executionId. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/{automationId}/runs

**Run log**

`operationId: AutomationController_runsLog`

Runs of this automation, newest first, paged. `status` takes a comma-separated list; `stepId` with `outcome` (succeeded | failed) keeps runs where that step had that outcome; `q` searches the runs; `from`/`to` bound the start time.

#### Signature

```http
GET /automation/{automationId}/runs (automationId: string, status?: string, stepId?: string, outcome?: string, q?: string, from?: string, to?: string, page?: integer, pageSize?: integer) -> { total, page, pageSize, pages, data }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |
| `status` | query | string | — |  |
| `stepId` | query | string | — |  |
| `outcome` | query | "succeeded" \| "failed" | — |  |
| `q` | query | string | — |  |
| `from` | query | string | — |  |
| `to` | query | string | — |  |
| `page` | query | integer | — |  |
| `pageSize` | query | integer | — | Max 200. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | { total, page, pageSize, pages, data } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/{automationId}/steps/{stepId}/outcomes

**One step across runs**

`operationId: AutomationController_stepOutcomes`

For every run that reached this step, newest first: its outcome, duration, what it produced or the error, and where the flow went next. `outcome` narrows to succeeded or failed.

#### Signature

```http
GET /automation/{automationId}/steps/{stepId}/outcomes (automationId: string, stepId: string, outcome?: string, q?: string, page?: integer, pageSize?: integer) -> { step, totals: { reached, succeeded, failed }, total, page, pageSize, pages, data }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |
| `stepId` | path | string | yes | Step id in the workflow. |
| `outcome` | query | "succeeded" \| "failed" | — |  |
| `q` | query | string | — |  |
| `page` | query | integer | — |  |
| `pageSize` | query | integer | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | { step, totals: { reached, succeeded, failed }, total, page, pageSize, pages, data } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Automation not found — No automation with that id. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/{automationId}/monitor

**Monitor an automation**

`operationId: AutomationController_monitor`

The monitoring page in one call for the last `days` (default 14): the automation and whether its trigger is registered (re-registered first if it had dropped), run counts and rates, runs in flight, per-step figures (ran, failed, average ms, last error) and errors grouped by message.

#### Signature

```http
GET /automation/{automationId}/monitor (automationId: string, days?: integer) -> { automation, … }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |
| `days` | query | integer | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | { automation, … } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Automation not found — No automation with that id. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/{automationId}/check

**Check an automation before running it**

`operationId: AutomationController_checkAutomation`

What stands between this workflow and running, step by step, so problems show before anyone presses Start. Nothing is run.

#### Signature

```http
GET /automation/{automationId}/check (automationId: string) -> { ready, problems }
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | AUTOMATION_NOT_FOUND | Automation not found | No automation with that id. | — |

Plus the standard platform errors: `401`, `403`, `429`, `500`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | { ready, problems } |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Automation not found — No automation with that id. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /automation/{automationId}

**Get an automation**

`operationId: AutomationController_getAutomation`

One automation with its trigger, conditions and actions.

#### Signature

```http
GET /automation/{automationId} (automationId: string) -> The automation
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `PUT /automation/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The automation |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## PUT /automation/{automationId}

**Update an automation**

`operationId: AutomationController_updateAutomation`

Changes an automation's definition. Editing a **running** automation changes what fires from the next trigger onward — stop it first if the edit is not one you want taking effect mid-way.

#### Signature

```http
PUT /automation/{automationId} (automationId: string, body) -> The updated automation
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Takes effect immediately on a running automation.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/stop/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Request body

Fields to change.

```json
{
  "actions": [
    {
      "type": "send-email",
      "template": "welcome-v2"
    }
  ]
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The updated automation |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## DELETE /automation/{automationId}

**Delete an automation**

`operationId: AutomationController_deleteAutomation`

Removes an automation and its execution history. Stop it rather than delete it if the history matters — the record of what it did goes with it.

#### Signature

```http
DELETE /automation/{automationId} (automationId: string, body) -> The result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Discards execution history.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/stop/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Request body

Optional options.

```json
{}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/{automationId}/execute

**Execute an automation now**

`operationId: AutomationController_executeAutomation`

Runs an automation immediately, outside its trigger. **Not a dry run** — the actions happen for real, including anything that sends or charges.

Use it to test with a deliberately harmless payload, or to re-run a case that should have fired and did not.

#### Signature

```http
POST /automation/{automationId}/execute (automationId: string, body) -> The execution result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Real side effects — not a simulation.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/ai/validate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `automationId` | path | string | yes | Automation id. |

### Request body

The payload to run against.

```json
{
  "record": {
    "id": "CUST-4821",
    "email": "ada@example.com"
  }
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The execution result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/ai/generate

**Generate an automation from a description**

`operationId: AutomationAiController_generateAutomation`

Drafts an automation definition from plain language. The output is a **draft**: it is created stopped and should be read before being armed, because a plausible-looking trigger can match far more than intended.

Consumes AI credit.

#### Signature

```http
POST /automation/ai/generate (body) -> The drafted automation
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Review before starting. Consumes AI credit.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/ai/validate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

What the automation should do.

```json
{
  "prompt": "When a new customer signs up, wait a day, then email them a getting-started guide."
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Returns the generated automation workflow JSON |
| `201` | The drafted automation |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/ai/improve

**Suggest automation improvements**

`operationId: AutomationAiController_improveAutomation`

Reviews an existing automation and suggests changes. Suggestions only — nothing is applied.

#### Signature

```http
POST /automation/ai/improve (body) -> Suggestions
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Read-only. Consumes AI credit.

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `PUT /automation/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The automation to review.

```json
{
  "automationId": "AUT-4821"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | Suggestions |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/ai/validate

**Validate an automation**

`operationId: AutomationAiController_validateAutomation`

Checks an automation definition for problems before it is armed — missing fields, unreachable conditions, actions that will fail. The cheap check to run between drafting and starting.

#### Signature

```http
POST /automation/ai/validate (body) -> The validation result
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/start/{automationId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The definition to check.

```json
{
  "trigger": {
    "type": "record.created",
    "datatype": "customer"
  },
  "actions": [
    {
      "type": "send-email",
      "template": "welcome"
    }
  ]
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The validation result |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /automation/ai/templates

**Get automation templates**

`operationId: AutomationAiController_getAutomationTemplates`

Suggested starting points for a described goal — templates to adapt rather than write from scratch.

#### Signature

```http
POST /automation/ai/templates (body) -> Templates
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

Plus the standard platform errors: `401`, `403`, `429`, `500`.

#### See also

- `POST /automation/ai/generate`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

What you are trying to automate.

```json
{
  "goal": "follow up on abandoned carts"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | Templates |
| `401` | Authentication failed: Invalid or expired token — The `Authorization` header is missing, malformed, or the JWT has expired. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |