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.

This page as Markdown

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 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 and 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.

bash

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'

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

{
  "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.

bash

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

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

{
  "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 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 for them.

Response

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

bash

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
  }'

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

{
  "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, as it was before the delete.

bash

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

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

{
  "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"
}

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 https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/environments/prd7k2/buckets/k3m9p2x/workflows/authentication \
  -H "Authorization: Bearer $APITRAFFIC_SESSION_TOKEN"

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

{
  "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.

Workflows: Build a workflow and choose what it does.
Stream views: The stream views that start workflows.

Workflows API

The workflow object #

List workflows #

Path parameters #

Query parameters #

Response #

Get workflow #

Path parameters #

Response #

Create workflow #

Path parameters #

Body parameters #

Response #

Delete workflow #

Path parameters #

Response #

Sign in to the workflow builder #

Path parameters #

Response #

Errors #

Related #

The workflow object

List workflows

Path parameters

Query parameters

Response

Get workflow

Path parameters

Response

Create workflow

Path parameters

Body parameters

Response

Delete workflow

Path parameters

Response

Sign in to the workflow builder

Path parameters

Response

Errors

Related