> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/create-an-automation.md).

# Create an Automation

### Before you begin

To create an automation, you need:

* an account ID
* a bearer token for API authorization
* at least two automation types for the workflow
* credentials for automation types that access external services

You can retrieve the currently available automation types and their configuration schemas using:

```http
GET /api/v1/automation/account/{accountId}/brick-types
```

Use the returned `configSchema` for the selected type to determine which configuration fields it supports.

### Workflow structure

An automation contains the following properties:

```json
{
  "name": "Automation name",
  "active": true,
  "workflow": []
}
```

<table><thead><tr><th width="304.20001220703125">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Automation name</td></tr><tr><td><code>active</code></td><td>Whether the automation is active</td></tr><tr><td><code>workflow</code></td><td>Workflow items performed by the automation</td></tr></tbody></table>

The `workflow` array contains the operations performed by the automation. A workflow must contain at least two items.

Each workflow item uses the following structure:

```json
{
  "id": "uuid",
  "type": "automation-type",
  "description": "Description",
  "config": {},
  "credentialsId": "uuid",
  "next": []
}
```

<table><thead><tr><th width="149.79998779296875">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>UUID generated for the workflow item</td></tr><tr><td><code>type</code></td><td>Automation type, such as <code>envelope-trigger</code></td></tr><tr><td><code>description</code></td><td>Optional description of the operation</td></tr><tr><td><code>config</code></td><td>Configuration for the selected automation type, defined by its <code>configSchema</code></td></tr><tr><td><code>credentialsId</code></td><td>ID of stored credentials, included only when the selected type requires credentials</td></tr><tr><td><code>next</code></td><td>IDs of workflow items that receive this item's output</td></tr></tbody></table>

Use `x` and `y` to set an item's position on the workflow canvas. They do not affect execution.

### Passing data between automation types

Automation types can expose named output parameters. Downstream workflow items receive them automatically when parameter names match.

For example, `envelope-trigger` provides:

```
envelope
mailbox
```

The `envelope-label-assignee` type requires `envelope`, `mailbox`, and `label`. When it follows `envelope-trigger`, the `envelope` and `mailbox` values are supplied automatically, so only `label` needs to be specified in its `config`.

### Create an automation

The following example creates an automation that detects envelopes with the `WAITING` status and assigns the `AutoProcessed` label to them.

#### Get the available automation types

Send:

```http
GET /api/v1/automation/account/{accountId}/brick-types
```

Find `envelope-trigger` and `envelope-label-assignee` in the response and use their `configSchema` definitions when configuring the workflow.

#### Build the workflow

Use the following payload:

```json
{
  "name": "Catch envelopes in 'Waiting for you' status and assign a label to them",
  "active": true,
  "workflow": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "envelope-trigger",
      "description": "Catch envelopes in 'Waiting for you' status",
      "config": {
        "status": [
          "WAITING"
        ]
      },
      "next": [
        "22222222-2222-2222-2222-222222222222"
      ]
    },
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "type": "envelope-label-assignee",
      "description": "Assign label",
      "config": {
        "label": "AutoProcessed"
      },
      "next": []
    }
  ]
}
```

The `next` value in `envelope-trigger` contains the ID of `envelope-label-assignee`. This makes label assignment the next operation. The final operation uses an empty `next` array.

#### Create the automation

Send the workflow using:

```http
POST /api/v1/automation/account/{accountId}
```

A successful request returns `201 Created` with the automation ID:

```json
{
  "id": "<automation-uuid>"
}
```

#### Trigger the automation

Perform the action that matches the configured trigger. For this example, an envelope must enter a status matched by the `envelope-trigger` configuration.

The example uses:

```json
{
  "status": [
    "WAITING"
  ]
}
```

Supported envelope status values:

{% columns %}
{% column %}

* `DRAFT`
* `SENT`
* `WAITING`
  {% endcolumn %}

{% column %}

* `COMPLETED`
* `CANCELLED`
  {% endcolumn %}

{% column %}

* `EXPIRED`
* `ON_APPROVAL`
  {% endcolumn %}
  {% endcolumns %}

When the trigger finds a matching envelope, the workflow continues to `envelope-label-assignee`. The first run creates the `AutoProcessed` label if it does not exist.

#### Verify the execution

Creating an automation successfully does not confirm that its workflow has executed successfully. After triggering it, retrieve the automation executions:

```http
GET /api/v1/automation/account/{accountId}/executions
```

Find the corresponding execution and check its execution state.

A completed execution has state `SUCCEED`.

If the execution state is `FAILED`, retrieve its execution log:

```http
GET /api/v1/automation/account/{accountId}/execution/{traceId}/log
```

The log identifies the failed workflow item and describes the error.

### Related topics

* [Automation types](/automation-types.md)
* [Automation Overview](/automation-overview.md)