Managing Flows

Everything you do with a flow after writing its definition: create it, save changes, publish, pause, retire, copy.

Lifecycle

Flows are versioned, so you can edit safely while the old version keeps running.

Create with POST /api/v1/automations. The flow starts as a DRAFT and never runs.
Save changes with PATCH /api/v1/automations/:id and a definition. This saves a draft. If the flow is already live, the live version keeps running untouched.
Publish with POST /api/v1/automations/:id/publish. We validate the draft, make it the live version and set the flow to ACTIVE.

Nothing you edit goes live until you publish it.

Recommended rhythm: PATCH the definition, then publish with an empty body. Publish also accepts a definition in its body, but that skips the draft. Test runs always use the saved draft when there is one, so publishing a definition that was never saved as a draft leaves your tests running an older version.

Flow status	Meaning	How you get there
`DRAFT`	Never published. Doesn’t run.	Create
`ACTIVE`	Live. Runs on every matching event.	Publish, or activate a paused flow
`PAUSED`	Temporarily off. Keeps its configuration.	Pause
`ARCHIVED`	Retired. Doesn’t run until you activate or publish it again.	Archive

The Flow Object

Every flow endpoint except DELETE returns the flow with its current versions:

{
  "id": "flow_abc",
  "teamId": "team_123",
  "name": "Reel drop - comment LINK to get the link",
  "status": "ACTIVE",
  "platformScope": "INSTAGRAM",
  "createdAt": "2026-09-20T10:00:00.000Z",
  "updatedAt": "2026-09-26T09:00:00.000Z",
  "publishedVersion": {
    "id": "ver_3",
    "version": 3,
    "status": "PUBLISHED",
    "publishedAt": "2026-09-26T09:00:00.000Z",
    "definition": { "trigger": { "...": "..." }, "steps": [] }
  },
  "draftVersion": {
    "id": "ver_1",
    "version": 1,
    "status": "DRAFT",
    "definition": { "trigger": { "...": "..." }, "steps": [] }
  }
}

publishedVersion is what runs. It’s missing until the first publish.
draftVersion is your latest saved draft. It stays after publishing, so right after a publish both usually carry the same definition. The next PATCH overwrites the draft in place, so the draft keeps its version number while each publish creates a new, higher one.
Every run in the execution logs records the flowVersionId it used, so you can tell which version answered.

List Flows

Endpoint: GET /api/v1/automations?teamId=team_123 Optional filters: status, platformScope, socialAccountId (matches flows whose published version listens on that account, so drafts don’t show up here), plus offset and limit (default 10). Returns { items, total }, newest first. Archived flows are included, filter with status if you don’t want them. Endpoint: GET /api/v1/automations/:id returns a single flow.

Create, Edit, Publish

platformScope is the flow’s platform label: INSTAGRAM, FACEBOOK, TIKTOK, or BOTH (Instagram or Facebook). It has to fit the trigger’s platform. A flow has exactly one trigger, so it listens on one account. Want the same automation on Instagram and Facebook? Create two flows. The flow name can be up to 120 characters.

const API = "https://api.bundle.social/api/v1";
const headers = {
  "Content-Type": "application/json",
  "x-api-key": process.env.BUNDLE_API_KEY,
};

// 1. Create (you can pass the definition right away, or add it later with PATCH)
const flow = await fetch(`${API}/automations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    teamId: "team_123",
    name: "Reel drop - comment LINK to get the link",
    platformScope: "INSTAGRAM",
    definition: {
      trigger: {
        type: "COMMENT_CREATED",
        platform: "INSTAGRAM",
        socialAccountId: "sa_789",
        postId: "post_123",
        keywords: ["link"],
      },
      steps: [
        { type: "SEND_PRIVATE_REPLY", message: { text: "Here's the link 🔗 https://yourshop.com/drop" } },
        { type: "SEND_PUBLIC_COMMENT_REPLY", text: "Check your DMs 👀" },
      ],
    },
  }),
}).then((r) => r.json());

// 2. Publish - validates everything and makes it live
const res = await fetch(`${API}/automations/${flow.id}/publish`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});

if (!res.ok) {
  // 400: schema problems come in `issues`, the rest in `message` separated by "; "
  const err = await res.json();
  console.error(err.issues ?? err.message);
}

// 3. Later: change the reply text, then publish again
await fetch(`${API}/automations/${flow.id}`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ definition: { /* full definition with your changes */ } }),
});
await fetch(`${API}/automations/${flow.id}/publish`, { method: "POST", headers, body: JSON.stringify({}) });

PATCH accepts name, platformScope and definition, all optional. A definition always replaces the whole draft, so send the full trigger and all steps, not just the part you changed. Validation runs on create and on every PATCH that carries a definition, and again on publish. It happens in two stages:

Shape (field types, lengths, counts, duplicate step ids): a 400 with an issues array, one entry per problem with its path.
Everything else (accounts, permissions, the post, whether steps fit the trigger), once the shape is valid: all problems come back in one 400 whose message joins them with ; , so you can fix them in one go.

A TikTok comment flow is also rejected while comment import is off for your organization. Publishing a flow that has no draft and no definition in the body returns 400.

Pause, Activate, Archive, Delete

Endpoint	What happens
`POST /api/v1/automations/:id/pause`	The flow stops reacting to new events. Runs still waiting on a delay are canceled.
`POST /api/v1/automations/:id/activate`	A paused (or archived) flow goes live again with its published version. Returns `400` if the flow was never published.
`POST /api/v1/automations/:id/archive`	Retired. Stops running, waiting runs are canceled. Still listed and readable, and it comes back if you activate or publish it again.
`DELETE /api/v1/automations/:id`	Gone. Waiting runs are canceled and the flow answers `404` from now on. Past runs stay readable by their ID via `GET /api/v1/automation-executions/:id` until they’re 30 days old.

None of these take a body.

Copy Flows Between Teams

Endpoint: POST /api/v1/automations/copy

{ "sourceTeamId": "team_123", "targetTeamId": "team_456", "flowId": "flow_abc" }

Leave out flowId to copy every flow of the source team (archived ones included). Copies land as drafts in the target team, with the account-specific bits cleared (socialAccountId, postId, senderExternalIds). Point them at the new team’s accounts with PATCH, then publish. Perfect for agencies rolling out the same automations to many clients. Create and copy answer 201. Copy returns { items, total } with the new flows. Source and target team must be different.

API Documentation

Platforms

Guides

Endpoints

Lifecycle

The Flow Object

List Flows

Create, Edit, Publish

Pause, Activate, Archive, Delete

Copy Flows Between Teams

​Lifecycle

​The Flow Object

​List Flows

​Create, Edit, Publish

​Pause, Activate, Archive, Delete

​Copy Flows Between Teams

Lifecycle

The Flow Object

List Flows

Create, Edit, Publish

Pause, Activate, Archive, Delete

Copy Flows Between Teams