# Flows

## Get Flows

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows`

Return all flows of a user.\
\
`curl "https://api.appmixer.com/flows" -H "Authorization: Bearer [ACCESS_TOKEN]"`

#### Query Parameters

| Name                  | Type   | Description                                                                                                                                                                                                                                                                                                                              |
| --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter                | string | Filter flows by their property values. Example: "userId:123abc" returns only flows who's owner is the user with ID "123abc" (i.e. shared flows are excluded). Note that you can also search on nested fields. This is especially useful with the `customFields` metadata object. For example: "filter=customFields.category:healthcare". |
| sharedWithPermissions | string | Filter flows by their sharing setting. Example: "read,start". All possible permission are currently "read", "start", "stop".                                                                                                                                                                                                             |
| projection            | string | Exclude flow object properties. Example: "-flow,-thumbnail".                                                                                                                                                                                                                                                                             |
| sort                  | string | Sorting parameter. Can be any flow object property followed by semicolon and 1 (ascending), -1 (descending). Example: "mtime:-1".                                                                                                                                                                                                        |
| pattern               | string | A term to filter flows containing pattern in their *name* or *flowId* property.                                                                                                                                                                                                                                                          |
| offset                | number | The index of the first item returned. Default is 0. Useful for paging.                                                                                                                                                                                                                                                                   |
| limit                 | number | Maximum items returned. Default is 100. Useful for paging.                                                                                                                                                                                                                                                                               |

{% tabs %}
{% tab title="200 Flows successfully retrieved." %}

```javascript
[
  {
    "userId": "58593f07c3ee4f239dc69ff7",
    "flowId": "9089f275-f5a5-4796-ba23-365412c5666e",
    "stage": "stopped",
    "name": "Flow #4",
    "btime": "2018-03-29T19:24:08.950Z",
    "mtime": "2018-04-05T12:50:15.952Z",
    "sharedWith": [{
      "email": "david@client.io",
      "permissions": ["read", "start", "stop"]
    }],
    "flow": {
      "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
        "type": "appmixer.utils.http.Uptime",
        "label": "Uptime",
        "source": {},
        "x": 110,
        "y": 90,
        "config": {}
      },
      "43f1f63a-ecd2-42dc-a618-8c96b4acc767": {
        "type": "appmixer.utils.email.SendEmail",
        "label": "SendEmail",
        "source": {
          "in": {
            "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": [
              "up"
            ]
          }
        },
        "x": 320,
        "y": -10,
        "config": {
          "transform": {
            "in": {
              "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
                "up": {
                  "type": "json2new",
                  "lambda": {
                    "from_email": "info@appmixer.com",
                    "text": "Site {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.target}}} is back UP.\nDowntime: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.downTimeText}}}\nHTTP Status Code: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.statusCode}}}",
                    "subject": "Appmixer: Site UP ({{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.target}}})"
                  }
                }
              }
            }
          }
        }
      },
      "416150af-b0d4-4d06-8ad1-75b17e578532": {
        "type": "appmixer.utils.email.SendEmail",
        "label": "SendEmail",
        "source": {
          "in": {
            "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": [
              "down"
            ]
          }
        },
        "x": 320,
        "y": 195,
        "config": {
          "transform": {
            "in": {
              "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
                "down": {
                  "type": "json2new",
                  "lambda": {
                    "from_email": "info@appmixer.com",
                    "subject": "Appmixer: Site DOWN ({{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.target}}})",
                    "text": "Site {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.target}}} is DOWN.\nHTTP Status Code: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.statusCode}}}"
                  }
                }
              }
            }
          }
        }
      }
    },
    "mode": "module",
    "thumbnail": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20xmlns%3Axlink%3D...",
    "started": "2018-04-05T12:33:15.357Z"
  },
  {
    "userId": "58593f07c3ee4f239dc69ff7",
    "flowId": "93198d48-e680-49bb-855c-58c2c11d1857",
    "stage": "stopped",
    "name": "Flow #5",
    "btime": "2018-04-03T15:48:52.730Z",
    "mtime": "2018-04-11T07:41:22.767Z",
    "flow": {
      "ce0742f4-4f72-4ea2-bea6-62cfaa2def86": {
        "type": "appmixer.utils.email.SendEmail",
        "label": "SendEmail",
        "source": {
          "in": {
            "3d71d67f-df0b-4723-bf85-20c97f6eaff6": [
              "weather"
            ]
          }
        },
        "x": 485,
        "y": 95,
        "config": {
          "transform": {
            "in": {
              "3d71d67f-df0b-4723-bf85-20c97f6eaff6": {
                "weather": {
                  "type": "json2new",
                  "lambda": {
                    "from_email": "info@appmixer.com",
                    "subject": "Appmixer: Current Weather",
                    "text": "Temperature: {{{$.3d71d67f-df0b-4723-bf85-20c97f6eaff6.weather.main.temp}}} dgC\nPressure: {{{$.3d71d67f-df0b-4723-bf85-20c97f6eaff6.weather.main.pressure}}} hPa\nHumidity: {{{$.3d71d67f-df0b-4723-bf85-20c97f6eaff6.weather.main.humidity}}}%\nCloudiness: {{{$.3d71d67f-df0b-4723-bf85-20c97f6eaff6.weather.clouds.all}}}%",
                    "to": ""
                  }
                }
              }
            }
          }
        }
      },
      "3d71d67f-df0b-4723-bf85-20c97f6eaff6": {
        "type": "appmixer.utils.weather.GetCurrentWeather",
        "label": "GetCurrentWeather",
        "source": {
          "location": {
            "b4d1ddbc-4bed-4de3-8fe1-9d9542d03cf0": [
              "out"
            ]
          }
        },
        "x": 290,
        "y": 95,
        "config": {
          "transform": {
            "location": {
              "b4d1ddbc-4bed-4de3-8fe1-9d9542d03cf0": {
                "out": {
                  "type": "json2new",
                  "lambda": {
                    "city": "Prague",
                    "units": "metric"
                  }
                }
              }
            }
          }
        }
      },
      "b4d1ddbc-4bed-4de3-8fe1-9d9542d03cf0": {
        "type": "appmixer.utils.controls.OnStart",
        "label": "OnStart",
        "source": {},
        "x": 105,
        "y": 95,
        "config": {}
      }
    },
    "mode": "module",
    "thumbnail": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20xmlns%3Axlink%3D...",
    "started": "2018-04-06T12:59:29.631Z"
  }
]
```

{% endtab %}
{% endtabs %}

## Get Flow

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:id`

Return one flow.\
\
`curl "https://api.appmixer.com/flows/9089f275-f5a5-4796-ba23-365412c5666e" -H "Authorization: Bearer [ACCESS_TOKEN]"`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string |             |

{% tabs %}
{% tab title="200 Flow successfully retrieved" %}

```javascript
{
  "userId": "58593f07c3ee4f239dc69ff7",
  "flowId": "9089f275-f5a5-4796-ba23-365412c5666e",
  "stage": "stopped",
  "name": "Flow #4",
  "btime": "2018-03-29T19:24:08.950Z",
  "mtime": "2018-04-05T12:50:15.952Z",
  "flow": {
    "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
      "type": "appmixer.utils.http.Uptime",
      "label": "Uptime",
      "source": {},
      "x": 110,
      "y": 90,
      "config": {}
    },
    "43f1f63a-ecd2-42dc-a618-8c96b4acc767": {
      "type": "appmixer.utils.email.SendEmail",
      "label": "SendEmail",
      "source": {
        "in": {
          "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": [
            "up"
          ]
        }
      },
      "x": 320,
      "y": -10,
      "config": {
        "transform": {
          "in": {
            "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
              "up": {
                "type": "json2new",
                "lambda": {
                  "from_email": "info@appmixer.com",
                  "text": "Site {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.target}}} is back UP.\nDowntime: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.downTimeText}}}\nHTTP Status Code: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.statusCode}}}",
                  "subject": "Appmixer: Site UP ({{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.up.target}}})"
                }
              }
            }
          }
        }
      }
    },
    "416150af-b0d4-4d06-8ad1-75b17e578532": {
      "type": "appmixer.utils.email.SendEmail",
      "label": "SendEmail",
      "source": {
        "in": {
          "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": [
            "down"
          ]
        }
      },
      "x": 320,
      "y": 195,
      "config": {
        "transform": {
          "in": {
            "e15ef119-8fcb-459b-aaae-2a3f9ee41f15": {
              "down": {
                "type": "json2new",
                "lambda": {
                  "from_email": "info@appmixer.com",
                  "subject": "Appmixer: Site DOWN ({{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.target}}})",
                  "text": "Site {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.target}}} is DOWN.\nHTTP Status Code: {{{$.e15ef119-8fcb-459b-aaae-2a3f9ee41f15.down.statusCode}}}"
                }
              }
            }
          }
        }
      }
    }
  },
  "mode": "module",
  "thumbnail": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20xmlns%3Axlink%3D...",
  "started": "2018-04-05T12:33:15.357Z"
}
```

{% endtab %}
{% endtabs %}

## Get Flows Count

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/count`

Return the number of all flows of a user.\
\
`curl "https://api.appmixer.com/flows/count" -H "Authorization: Bearer [ACCESS_TOKEN]"`

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "count": 29
}    
```

{% endtab %}
{% endtabs %}

## Create Flow

<mark style="color:green;">`POST`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows`

Create a new flow.\
\
`curl -XPOST "https://api.appmixer.com/flows" -H "Content-Type: application/json" -d '{ "flow": FLOW_DESCRIPTOR, "name": "My Flow #1", "customFields": { "category": "healthcare" } }'`

#### Request Body

| Name         | Type   | Description                                                                                                                                        |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string | Name of the flow.                                                                                                                                  |
| customFields | object | An object with any custom properties. This is useful for storing any custom metadata and later using the metadata values to filter returned flows. |
| thumbnail    | string | Flow thumbnail image.                                                                                                                              |
| flow         | object | Flow descriptor.                                                                                                                                   |
| wizard       | object | Wizard configuration for Integration Templates. See [Flow Wizard](#flow-wizard) for the full schema.                                               |
| notes        | object | Note blocks displayed in the Designer canvas. See [Flow Notes](#flow-notes) for the full schema.                                                   |

{% tabs %}
{% tab title="200 Flow successfully created." %}

```
{
    "flowId": "26544d8c-5209-44ac-9bdf-ef786924b07b"
}
```

{% endtab %}
{% endtabs %}

## Update Flow

<mark style="color:orange;">`PUT`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:id`

Update an existing flow.\
\
`curl -XPUT "https://api.appmixer.com/flows/9089f275-f5a5-4796-ba23-365412c5666e" -H "Content-Type: application/json" -d '{ "flow": FLOW_DESCRIPTOR, "name": "My Flow #2" }'`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Flow ID.    |

#### Query Parameters

<table><thead><tr><th width="201">Name</th><th width="147">Type</th><th>Description</th></tr></thead><tbody><tr><td>forceUpdate</td><td>boolean</td><td>A running flow cannot be updated unless forceUpdate=true.</td></tr></tbody></table>

#### Request Body

| Name | Type   | Description                                                                                                                                                                                      |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|      | object | An object with `flow`, `name`, `customFields`, `thumbnail`, `sharedWith`, `wizard`, and `notes` parameters. `flow` is the Flow descriptor. See [Flow Notes](#flow-notes) for the `notes` schema. |

{% tabs %}
{% tab title="200 " %}

```
{
    "flowId": "26544d8c-5209-44ac-9bdf-ef786924b07b",
    "result": "updated"
}
```

{% endtab %}
{% endtabs %}

## Delete Flow

<mark style="color:red;">`DELETE`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:id`

Delete an existing flow.\
\
`curl -XDELETE "https://api.appmixer.com/flows/9089f275-f5a5-4796-ba23-365412c5666e" -H "Authorization: Bearer [ACCESS_TOKEN]"`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Flow ID.    |

{% tabs %}
{% tab title="200 " %}

```
{
    "flowId": "26544d8c-5209-44ac-9bdf-ef786924b07b"
}
```

{% endtab %}
{% endtabs %}

## Clone Flow

<mark style="color:green;">`POST`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:id/clone`

Clone a flow

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String | Flow ID     |

#### Request Body

| Name               | Type    | Description                                                                                                                                                                                                                                                                               |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prefix             | String  | Prefix for flow clone name. The original flow name will be used with this prefix as a name for the new flow.                                                                                                                                                                              |
| projection         | String  | <p>Properties to be filtered from the flow model.</p><p>Example: "-thumbnail,-sharedWith". With this projection string, the thumbnail and sharedWith property will not be cloned.</p>                                                                                                     |
| connectAccounts    | Boolean | If user accounts (like Gmail account for SendEmail component) connected to the source flow components should also be connected to cloned flow components. Default is false. Accounts can be connected only if the owner of the cloned flow is the same as the owner of the original flow. |
| isTemplateInstance | Boolean | If source flow is an instance of template (related to Integrations). Default is false                                                                                                                                                                                                     |
| setOriginFlowId    | Boolean | Default false. If true, the originFlowId property of the clone will be set to the original flow.                                                                                                                                                                                          |
| setComponentIdMap  | Boolean | Default true. Stores a map of the component IDs from the original flow to the component IDs in the clone. This is later used in Integrations when performing updates of the Integration Templates.                                                                                        |
| additional         | Object  | `sharedWith`, `type` and `wizard` properties can be set in this object.                                                                                                                                                                                                                   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "cloneId": "cloned-flow-id"
}
```

{% endtab %}
{% endtabs %}

## Flow Drafts

Flow Drafts allow you to create editable versions of flows without affecting the original running flow. Drafts are primarily used for making changes to integration instances while the original continues to run.

### Overview

* **Draft Types**: `automation-draft` and `integration-instance-draft`
* **Workflow**: Create draft → Make changes → Publish to update original flow
* **Safety**: Only one draft per flow can exist at a time
* **Component ID Mapping**: Drafts maintain a mapping to original component IDs for seamless publishing

### Create a Draft

<mark style="color:green;">`POST`</mark> `http://[API-URL]/flows/:id/clone`

Create a draft by cloning an existing flow with special draft parameters.

#### Path Parameters

| Name                                 | Type   | Description                  |
| ------------------------------------ | ------ | ---------------------------- |
| id<mark style="color:red;">\*</mark> | String | Flow ID to create draft from |

#### Request Body

| Name                                                | Type    | Description                                                                             |
| --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| setOriginFlowId<mark style="color:red;">\*</mark>   | Boolean | Must be `true` to link draft to original flow                                           |
| setComponentIdMap<mark style="color:red;">\*</mark> | Boolean | Must be `true` to map component IDs for publishing                                      |
| connectAccounts<mark style="color:red;">\*</mark>   | Boolean | Recommended `true` to copy account connections                                          |
| additional<mark style="color:red;">\*</mark>        | Object  | Must include `type` field set to `"automation-draft"` or `"integration-instance-draft"` |

```bash
curl -XPOST "http://[API-URL]/flows/9089f275-f5a5-4796-ba23-365412c5666e/clone" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-type: application/json" \
  -d '{
    "setOriginFlowId": true,
    "setComponentIdMap": true,
    "connectAccounts": true,
    "additional": {
      "type": "integration-instance-draft"
    }
  }'
```

{% tabs %}
{% tab title="200: OK Draft created successfully" %}

```javascript
{
  "cloneId": "draft-flow-id"
}
```

{% endtab %}

{% tab title="200: OK Existing draft returned" %}

```javascript
{
  "cloneId": "existing-draft-flow-id"
}
```

**Note:** If a draft of the same type already exists for this flow, the existing draft ID is returned instead of creating a duplicate.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Draft Uniqueness**

The API ensures only one draft per flow and type can exist. If you attempt to create a draft when one already exists, the API returns the existing draft's ID instead of creating a duplicate.
{% endhint %}

### Publish a Draft

<mark style="color:green;">`POST`</mark> `http://[API-URL]/drafts/:draftFlowId/publish`

Publish a draft to update the original flow with the draft's changes.

#### Path Parameters

| Name                                          | Type   | Description              |
| --------------------------------------------- | ------ | ------------------------ |
| draftFlowId<mark style="color:red;">\*</mark> | String | Draft flow ID to publish |

```bash
curl -XPOST "http://[API-URL]/drafts/draft-flow-id/publish" \
  -H "Authorization: Bearer [ACCESS_TOKEN]"
```

{% tabs %}
{% tab title="200: OK Draft published successfully" %}

```javascript
{
  "success": true,
  "flowId": "original-flow-id"
}
```

{% endtab %}

{% tab title="403: Forbidden User does not own the draft" %}

```javascript
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have permission to publish this draft."
}
```

{% endtab %}

{% tab title="404: Not Found Draft not found or not a draft type" %}

```javascript
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Draft not found or invalid draft type."
}
```

{% endtab %}
{% endtabs %}

### Publishing Process

When you publish a draft, the following operations occur automatically:

1. **Component ID Mapping**: Draft component IDs are mapped back to the original flow's component IDs
2. **Flow Update**: The original flow is updated with the draft's configuration
3. **Draft Deletion**: The draft flow is automatically deleted after successful publishing
4. **Account Connections**: If accounts were connected during draft creation, they are preserved

{% hint style="warning" %}
**Publishing Impact**

Publishing a draft will immediately update the original flow. If the original flow is running, the changes will take effect.
{% endhint %}

### Use Cases

**Editing Integration Instances**

* Create a draft of a running integration instance
* Make and test changes in the draft without affecting the live instance
* Publish when ready to update the running instance

## Start/Stop Flow

<mark style="color:green;">`POST`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:id/coordinator`

Start or stop an existing flow.\
\
`curl -XPOST "https://api.appmixer.com/flows/9089f275-f5a5-4796-ba23-365412c5666e" -H "Content-Type: application/json" -d '{ "command": "start" }'`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Flow ID.    |

#### Query Parameters (only for the stop command)

| Name       | Type    | Description                                                                                                                                                    |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| background | boolean | Will trigger the stop command, but won't wait for it to finish. Then you can use GET /flows/{flowId}/coordinator/status to check the status of that operation. |

#### Request Body

| Name    | Type   | Description                                                                          |
| ------- | ------ | ------------------------------------------------------------------------------------ |
| command | string | The command to send to the flow coordinator. It can be either `"start"` or `"stop"`. |

{% tabs %}
{% tab title="200 " %}

```json
{
    "flowId": "26544d8c-5209-44ac-9bdf-ef786924b07b",
    // equals the flowId if the background=true is sent in the query
    "ticket": "26544d8c-5209-44ac-9bdf-ef786924b07b"  
}
```

{% endtab %}
{% endtabs %}

## Get the status of the stop flow command

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/{flowId}/coordinator/status`

{% tabs %}
{% tab title="200 " %}

```json
{
    "status": "completed",
    "stepsTotal":1
}
```

{% endtab %}
{% endtabs %}

## Send GET request to a component

<mark style="color:blue;">`GET`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:flowId/components/:componentId`

**Query Parameters**

| Name        | Type    | Description                                                                                                                                                                                                                                                             |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enqueueOnly | Boolean | If "true" then the response to this request will be returned as soon as the requests is enqueued in the engine. It will not wait for the component to process the request and create the response. The response code is 202 in this case. The default value is "false". |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="202: Accepted If the component needs quota to process the webhook and it cannot get quota, Appmixer will return 202 and enqueue the incoming request for processing. It will be processed when quota is available." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Send POST request to a component

<mark style="color:green;">`POST`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:flowId/components/:componentId`

**Query Parameters**

| Name        | Type    | Description                                                                                                                                                                                                                                                             |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enqueueOnly | Boolean | If "true" then the response to this request will be returned as soon as the requests is enqueued in the engine. It will not wait for the component to process the request and create the response. The response code is 202 in this case. The default value is "false". |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="202: Accepted If the component needs quota to process the webhook and it cannot get quota, Appmixer will return 202 and enqueue the incoming request for processing. It will be processed when quota is available." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Send PUT request to a component

<mark style="color:orange;">`PUT`</mark> `https://api.YOUR_TENANT.appmixer.cloud/flows/:flowId/components/:componentId`

**Query Parameters**

| Name        | Type    | Description                                                                                                                                                                                                                                                             |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enqueueOnly | Boolean | If "true" then the response to this request will be returned as soon as the requests is enqueued in the engine. It will not wait for the component to process the request and create the response. The response code is 202 in this case. The default value is "false". |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="202: Accepted If the component needs quota to process the webhook and it cannot get quota, Appmixer will return 202 and enqueue the incoming request for processing. It will be processed when quota is available." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Flow Notes

The `notes` property holds the definitions of **note blocks** displayed on the Designer canvas. Notes are purely visual — they let flow authors annotate a canvas with Markdown-formatted text to explain intent, guide end-users, or document template behaviour.

The Designer writes this object automatically when notes are created or edited. You can also construct or patch it programmatically via the [Create Flow](#create-flow) and [Update Flow](#update-flow) endpoints.

### The `notes` object

`notes` is a map of **note ID → note object**. Each key is a UUID that uniquely identifies the note block.

```json
{
  "notes": {
    "ec488c75-b240-4b8a-8939-e05ba4af32a4": {
      "x": -368,
      "y": -128,
      "width": 432,
      "height": 288,
      "content": "## My note\n\nSupports **Markdown** content."
    }
  }
}
```

### Note object properties

| Property  | Type   | Description                                                                                                                                                   |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x`       | number | Horizontal position of the note block on the canvas (pixels, can be negative).                                                                                |
| `y`       | number | Vertical position of the note block on the canvas (pixels, can be negative).                                                                                  |
| `width`   | number | Width of the note block in pixels.                                                                                                                            |
| `height`  | number | Height of the note block in pixels.                                                                                                                           |
| `content` | string | Full CommonMark Markdown displayed inside the note block. Supports headings, bold, italic, inline code, fenced code blocks, links, images, tables, and lists. |

## Flow Wizard

A flow becomes an **Integration Template** when it has a non-empty `wizard` property. The `wizard` object defines the configuration form that end-users fill in when they activate an integration — rendered by the [`appmixer.ui.Wizard`](/appmixer-ui-sdk/ui-and-widgets/wizard.md) widget.

The Wizard Builder in the Designer writes this object automatically. For programmatic template creation — importing templates, scripting bulk updates, or building custom tooling — you can construct or patch the `wizard` field directly via the [Create Flow](#create-flow) and [Update Flow](#update-flow) endpoints.

### The `wizard` object

```json
{
  "wizard": {
    "fields": []
  }
}
```

`fields` is an ordered array of field objects. The Wizard widget renders them top to bottom. Authentication (`account`) fields are always sorted to the top of the form regardless of their position in the array.

### Field reference

Every field object shares a common set of properties:

| Property      | Type   | Description                                                                                       |
| ------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `type`        | string | Field type. See the field types below.                                                            |
| `label`       | string | Label shown to the end-user.                                                                      |
| `tooltip`     | string | Optional tooltip text.                                                                            |
| `placeholder` | string | Optional input placeholder text.                                                                  |
| `source`      | string | Path to the bound component input: `<componentId>.<descriptorPath>`. Not used by all field types. |
| `attrs`       | object | Type-specific attributes. Shape varies by `type` — see below.                                     |
| `options`     | object | Additional display or behaviour options.                                                          |

#### `inspectorField`

Exposes a single component input field to the end-user. This is the most common field type.

`source` format: `<componentId>.<descriptorPath>`, where `descriptorPath` mirrors the config transform path in the flow descriptor — for example `a0828f32.config.transform.in.76a77abf.out.lambda.channelId`.

```json
{
  "type": "inspectorField",
  "label": "Slack Channel",
  "tooltip": "The Slack channel to post into.",
  "placeholder": "#general",
  "source": "a0828f32.config.transform.in.76a77abf.out.lambda.channelId",
  "attrs": {},
  "options": {}
}
```

#### `account`

Renders an account/authentication selector for one or more components that share the same auth service. Account fields are always displayed at the top of the Wizard form.

| `attrs` property  | Type      | Description                                                                                |
| ----------------- | --------- | ------------------------------------------------------------------------------------------ |
| `service`         | string    | The auth service identifier, e.g. `"appmixer:slack"`.                                      |
| `components`      | string\[] | IDs of flow components that should use the selected account.                               |
| `sharedAccountId` | string    | Optional. When set, the Wizard pre-selects a specific shared account instead of prompting. |

```json
{
  "type": "account",
  "label": "Slack account",
  "tooltip": "",
  "attrs": {
    "service": "appmixer:slack",
    "components": ["a0828f32"],
    "sharedAccountId": null
  },
  "options": {}
}
```

#### `customField`

A field not bound to a specific component inspector input. Useful for injecting arbitrary data into a flow (e.g. via `customFields`).

| `attrs` property    | Type      | Description                                     |
| ------------------- | --------- | ----------------------------------------------- |
| `type`              | string    | Input type, e.g. `"text"`.                      |
| `path`              | string    | Data path the value is written to.              |
| `placeholder`       | string    | Input placeholder.                              |
| `searchPlaceholder` | string    | Placeholder for searchable select inputs.       |
| `service`           | string    | Optional linked auth service.                   |
| `components`        | string\[] | Optional linked component IDs.                  |
| `options`           | object    | Custom options passed to the field renderer.    |
| `params`            | object    | Custom parameters passed to the field renderer. |

```json
{
  "type": "customField",
  "label": "Customer ID",
  "tooltip": "",
  "placeholder": "e.g. CUST-001",
  "attrs": {
    "type": "text",
    "path": "customFields.customerId",
    "placeholder": "e.g. CUST-001",
    "searchPlaceholder": null,
    "service": null,
    "components": null,
    "options": {},
    "params": {}
  },
  "options": {}
}
```

#### `text`

A non-interactive content block — a heading or informational paragraph displayed inside the Wizard form.

| `attrs` property | Type   | Description                      |
| ---------------- | ------ | -------------------------------- |
| `format`         | string | Content format, e.g. `"header"`. |
| `text`           | string | The text content to display.     |

```json
{
  "type": "text",
  "label": "",
  "tooltip": "",
  "attrs": {
    "format": "header",
    "text": "Configure your Slack alarm"
  },
  "options": {}
}
```

#### `image`

A static image displayed inside the Wizard form.

| `attrs` property | Type   | Description        |
| ---------------- | ------ | ------------------ |
| `image`          | string | Image URL or path. |

```json
{
  "type": "image",
  "label": "",
  "tooltip": "",
  "attrs": {
    "image": "https://example.com/wizard-banner.png"
  },
  "options": {}
}
```

### Complete example

The following example creates an Integration Template programmatically. The flow has a Scheduler component (`76a77abf`) and a Slack `SendChannelMessage` component (`a0828f32`). The wizard exposes the Slack account selector and two input fields — the scheduled hour and the Slack channel.

```bash
curl -XPOST "https://api.YOUR_TENANT.appmixer.cloud/flows" \
  -H "Authorization: Bearer [ACCESS_TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alarm",
    "type": "integration-template",
    "flow": { ... },
    "wizard": {
      "fields": [
        {
          "type": "account",
          "label": "Slack account",
          "tooltip": "",
          "attrs": {
            "service": "appmixer:slack",
            "components": ["a0828f32"],
            "sharedAccountId": null
          },
          "options": {}
        },
        {
          "type": "inspectorField",
          "label": "Hour",
          "tooltip": "The hour (0–23) at which the alarm fires.",
          "placeholder": "",
          "source": "76a77abf.config.transform.in.trigger.out.lambda.hour",
          "attrs": {},
          "options": {}
        },
        {
          "type": "inspectorField",
          "label": "Slack Channel",
          "tooltip": "The Slack channel to post the alarm message into.",
          "placeholder": "#general",
          "source": "a0828f32.config.transform.in.76a77abf.out.lambda.channelId",
          "attrs": {},
          "options": {}
        }
      ]
    }
  }'
```

### Filtering Integration Templates

An Integration Template is a flow that has a non-empty `wizard` property and no `templateId` property. To list all published templates:

```
GET /flows?filter=templateId:!&filter=wizard.fields
```

To list a user's integration instances (flows created from a template):

```
GET /flows?filter=templateId
```

{% hint style="info" %}
For a guided walkthrough of building and publishing templates using the no-code Studio, see [Build and Publish a Template](/getting-started/integrations.md).
{% endhint %}

### Send DELETE request to a component <a href="#send-delete-request-to-a-component" id="send-delete-request-to-a-component"></a>

<mark style="color:red;">`DELETE`</mark> `https://api.appmixer.com/flows/:flowId/components/:componentId`

**Query Parameters**

| Name        | Type    | Description                                                                                                                                                                                                                                                                          |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| enqueueOnly | Boolean | <p>If "true" then the response to this request will be returned as soon as the requests is enqueued in the engine. It will not wait for the component to process the request and create the response. The response code is 202 in this case. The default value is</p><p>"false".</p> |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/api/flows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.