# Workflows API

> Create, list, read and delete the workflows that run when requests match a stream view, and open the workflow builder for a signed-in user.

Source: https://www.apitraffic.io/docs/api-reference/workflows

A workflow runs automatically when a captured request matches one of your stream views: it can post the request to a webhook, notify a channel or call another service. You design what it does in the workflow builder inside the app; these operations create the workflow, attach it to a stream view, list and delete workflows, and sign a user in to the builder. See [Workflows](https://www.apitraffic.io/docs/workflows) for building one.

**Plan:** needs a plan that includes **Workflows**. Listing, reading and deleting existing workflows keep working if the plan changes; creating one and opening the builder do not. The number of workflows an account can keep depends on the plan.

**Permissions:** any member. [Create workflow](#create-workflow) and [Sign in to the workflow builder](#sign-in-to-the-workflow-builder) act for the person who is signed in, so call them with a user session rather than an API token.

## The workflow object

- **sid (string, required)**:
  The workflow's identifier (`flo_` followed by 27 letters and digits).

- **bucketSid (string, required)**:
  The bucket whose traffic the workflow watches.

- **name (string, required)**:
  The workflow's name.

- **enabled (boolean)**:
  Whether the workflow is turned on.

- **isPerEnvironment (boolean)**:
  Whether each environment has its own copy of the flow that can be edited separately.

- **externalWorkflowId (string)**:
  The flow's identifier in the workflow builder.

- **environmentExternalWorkflowId (string | null)**:
  In a list for one environment, the identifier of that environment's flow.

- **externalSystem (string)**:
  The builder the flow lives in.

- **attachedStreamViewCount (number)**:
  How many stream views trigger the workflow.

- **environments (object[])**:
  When known, the environments the workflow runs in: `sid`, `environmentSid`, `workflowSid`, `externalWorkflowId`, `enabled`, `createdAt` and `updatedAt`.

- **createdAt (string)**:
  When the workflow was created (ISO 8601).

## List workflows

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}/buckets/{bucketSid}/workflows`

Returns the workflows a stream view triggers in one environment, sorted by name. Pass both query parameters.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment.

- **bucketSid (path, string, required)**:
  The bucket.

### Query parameters

- **streamViewSid (query, string, required)**:
  The stream view whose workflows to list (`sv_…`).

- **environmentSid (query, string, required)**:
  The environment, the same as in the path.

### Response

- **hasMore (boolean, required)**:
  Always `false`.

- **records (object[], required)**:
  The workflows, as [workflow objects](#the-workflow-object).

```bash cURL
curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'streamViewSid=sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT' \
  --data-urlencode 'environmentSid=prd7k2'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({ streamViewSid: 'sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT', environmentSid: 'prd7k2' });
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/environments/prd7k2/buckets/k3m9p2x/workflows?${params}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const { records } = await response.json();
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
      "bucketSid": "k3m9p2x",
      "name": "Page on-call for payment failures",
      "enabled": true,
      "externalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
      "isPerEnvironment": false,
      "externalSystem": "activepieces",
      "environmentExternalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
      "attachedStreamViewCount": 0,
      "environments": [
        {
          "sid": "fle_2cN5mB7vX9zA1sD3fG6hJ8kL4qP",
          "environmentSid": "prd7k2",
          "workflowSid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
          "externalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
          "enabled": true,
          "createdAt": "2026-09-02T11:00:00.000Z",
          "updatedAt": "2026-09-02T11:00:00.000Z"
        }
      ],
      "createdAt": "2026-09-02T11:00:00.000Z"
    }
  ]
}
```

## Get workflow

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}/buckets/{bucketSid}/workflows/{workflowSid}`

Returns one workflow in the bucket.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment.

- **bucketSid (path, string, required)**:
  The bucket.

- **workflowSid (path, string, required)**:
  The workflow's identifier (`flo_…`).

### Response

A [workflow object](#the-workflow-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows/flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const workflowSid = 'flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/environments/prd7k2/buckets/k3m9p2x/workflows/${workflowSid}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const workflow = await response.json();
```

```json 200
{
  "sid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
  "bucketSid": "k3m9p2x",
  "name": "Page on-call for payment failures",
  "enabled": true,
  "externalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
  "isPerEnvironment": false,
  "externalSystem": "activepieces",
  "environmentExternalWorkflowId": null,
  "attachedStreamViewCount": 0,
  "createdAt": "2026-09-02T11:00:00.000Z"
}
```

## Create workflow

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}/buckets/{bucketSid}/workflows`

Creates a workflow in the bucket, with an empty flow in the builder, and attaches it to a stream view so that requests matching the view start it. Then open the builder with [Sign in to the workflow builder](#sign-in-to-the-workflow-builder) to add its steps.

**Plan:** needs **Workflows**; past the plan's workflow limit, the API answers `409` with code `2213`. **Permissions:** any member, with a user session.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment.

- **bucketSid (path, string, required)**:
  The bucket whose traffic the workflow watches.

### Body parameters

- **name (body, string, required)**:
  The workflow's name.

- **environmentSid (body, string, required)**:
  The environment (6 lowercase letters and digits), the same as in the path.

- **streamViewSid (body, string | null)**:
  The stream view (`sv_…`) whose matching requests start the workflow.

- **isPerEnvironment (body, boolean, default false)**:
  Give each environment its own copy of the flow, edited separately.

- **signin (body, boolean, default true)**:
  Accepted for compatibility. The response does not include sign-in details; call [Sign in to the workflow builder](#sign-in-to-the-workflow-builder) for them.

### Response

- **workflow (object, required)**:
  The new [workflow object](#the-workflow-object), with `connections`: the stream views attached to it, each with `sid`, `streamViewSid`, `workflowSid`, `properties`, `enabled` and `createdAt`.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows \
  -H "Authorization: Bearer $APITRAFFIC_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Page on-call for payment failures",
    "environmentSid": "prd7k2",
    "streamViewSid": "sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT",
    "isPerEnvironment": false
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/environments/prd7k2/buckets/k3m9p2x/workflows`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_SESSION_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Page on-call for payment failures',
      environmentSid: 'prd7k2',
      streamViewSid: 'sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT',
    }),
  },
);
const { workflow } = await response.json();
```

```json 200
{
  "workflow": {
    "sid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
    "bucketSid": "k3m9p2x",
    "name": "Page on-call for payment failures",
    "enabled": true,
    "externalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
    "isPerEnvironment": false,
    "externalSystem": "activepieces",
    "environmentExternalWorkflowId": null,
    "attachedStreamViewCount": 0,
    "createdAt": "2026-10-20T10:30:00.000Z",
    "connections": [
      {
        "sid": "wfc_2dP6nC8bV1xZ3aS5fG7hJ9kL4mQ",
        "streamViewSid": "sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT",
        "workflowSid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
        "properties": {},
        "enabled": true,
        "createdAt": "2026-10-20T10:30:00.000Z"
      }
    ]
  }
}
```

## Delete workflow

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}/buckets/{bucketSid}/workflows/{workflowSid}`

Deletes a workflow. Matching requests stop starting it straight away.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment.

- **bucketSid (path, string, required)**:
  The bucket.

- **workflowSid (path, string, required)**:
  The workflow's identifier.

### Response

The deleted [workflow object](#the-workflow-object), as it was before the delete.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows/flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const workflowSid = 'flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO';
await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/environments/prd7k2/buckets/k3m9p2x/workflows/${workflowSid}`,
  { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
```

```json 200
{
  "sid": "flo_2bM4nV6cX8zA1sD3fG5hJ7kL9pO",
  "bucketSid": "k3m9p2x",
  "name": "Page on-call for payment failures",
  "enabled": true,
  "externalWorkflowId": "Xk2pL9qR4tV7wZ1cB",
  "isPerEnvironment": false,
  "externalSystem": "activepieces",
  "environmentExternalWorkflowId": null,
  "attachedStreamViewCount": 0,
  "createdAt": "2026-10-20T10:30:00.000Z"
}
```

## Sign in to the workflow builder

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/environments/{environmentSid}/buckets/{bucketSid}/workflows/authentication`

Returns a short-lived token that opens the workflow builder as the signed-in user, for this account and environment. The app calls this when you open a workflow.

**Plan:** needs **Workflows**. **Permissions:** any member, with a user session.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **environmentSid (path, string, required)**:
  The environment.

- **bucketSid (path, string, required)**:
  The bucket.

### Response

- **embedToken (string, required)**:
  The token the builder is opened with. Treat it as a credential.

- **baseUrl (string, required)**:
  The builder's address.

- **user (object, required)**:
  The builder user the token signs in as.

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows/authentication \
  -H "Authorization: Bearer $APITRAFFIC_SESSION_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/environments/prd7k2/buckets/k3m9p2x/workflows/authentication`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_SESSION_TOKEN}` } },
);
const { embedToken, baseUrl } = await response.json();
```

```json 200
{
  "embedToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJ2ZXJzaW9uIjoidjMifQ.c2lnbmF0dXJl",
  "baseUrl": "https://flow.apitraffic.io"
}
```

The example leaves out `user`.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example an `environmentSid` that is not 6 lowercase letters and digits. |
| `400` | `3000` | The workflow could not be created. |
| `403` | `2221` | The plan does not include Workflows (create and sign-in). |
| `403` | `2509` | Creating a workflow on the read-only sample bucket. |
| `404` | `4000` | No workflow with that sid in this bucket, or the builder sign-in failed. |
| `409` | `2213` | The plan's workflow limit is reached. |

## Related

- [Workflows](https://www.apitraffic.io/docs/workflows):
    Build a workflow and choose what it does.

- [Stream views](https://www.apitraffic.io/docs/traffic/saved-views):
    The stream views that start workflows.