Creating Flows¶

Audience: Everyone · Tags: flow, create, api

Purpose. A flow is SnapLink's core unit of automation: Trigger → Actions. When the trigger fires, the actions run in order through a real execution engine, and every run is recorded so you can see exactly what happened. Creating a flow means defining that trigger and those actions, then approving them into a live version.

When to use. Any time you want an event in one app to cause something to happen in another — or the same — app, automatically.

Prerequisites. - A SnapLink account and workspace (workspaceId). - For actions that talk to a third-party app (Slack, Teams, HubSpot), that connector must be installed and connected in your workspace first — see Connect Your First App. The built-in Webhook trigger and Generic REST action need no connection.

Two ways to build a flow¶

Path	Best for	Where
Snap Studio (recommended)	Everyone — describe what you want in plain English, review the plan, save it	`/snap` in the app — see Snap Studio
Raw API	Developers, scripting, CI, or building your own UI on top of SnapLink	`POST /flows` → `POST /flows/:id/drafts` → `POST /drafts/:id/promote`

Both paths end at the same place: a flow with a promoted version. Snap Studio is a guided assistant that writes the flow definition for you and walks you through review and a test run before anything is saved — most people should start there. The rest of this guide covers the raw API path in full, for anyone building flows programmatically or who wants to understand what Snap Studio is doing under the hood.

Step-by-step: building a flow via the API¶

All requests below need Authorization: Bearer $TOKEN (get one from POST /auth/login) and use the base URL https://api.snaplink.cloudsolutionaccelerators.com/api/v1.

1. Create the flow shell¶

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_92a1c4f0e7b3",
    "name": "New lead to Slack",
    "description": "Alert #sales when a lead form fires"
  }'

Returns a Flow with status: "draft" and no version yet:

{ "ok": true, "data": {
  "id": "flow_1a2b3c4d5e6f",
  "workspaceId": "ws_92a1c4f0e7b3",
  "name": "New lead to Slack",
  "description": "Alert #sales when a lead form fires",
  "status": "draft",
  "activeVersionId": null,
  "createdAt": "2026-07-02T14:00:00.000Z",
  "updatedAt": "2026-07-02T14:00:00.000Z",
  "archivedAt": null
} }

2. Write a definition and create a draft¶

A flow definition has exactly one trigger and one or more actions. Today the only supported trigger is "webhook". Each action needs a key (unique within the flow), a connectorKey, an actionType, and an input object matching that action's fields.

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/flow_1a2b3c4d5e6f/drafts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "trigger": { "key": "trigger", "connectorKey": "webhook", "triggerType": "webhook" },
      "actions": [
        {
          "key": "notify",
          "connectorKey": "slack",
          "actionType": "send_message",
          "input": { "channel": "C0000000", "text": "New lead received" }
        }
      ]
    }
  }'

Returns a FlowDraft (status: "proposed"):

{ "ok": true, "data": {
  "id": "draft_9f8e7d6c5b4a",
  "flowId": "flow_1a2b3c4d5e6f",
  "workspaceId": "ws_92a1c4f0e7b3",
  "definition": { "...": "as sent" },
  "status": "proposed",
  "createdAt": "2026-07-02T14:01:00.000Z",
  "updatedAt": "2026-07-02T14:01:00.000Z"
} }

3. (Optional) Check it before you commit¶

POST /flow-designer/validate catches problems — a missing connector, a required field left blank, a connector that isn't installed yet — before you promote. See Flow Validation for the full list of checks.

4. Promote the draft¶

Promoting turns the draft into an immutable version and makes the flow's status "active". This is the human-approval step — nothing runs until you do this.

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/drafts/draft_9f8e7d6c5b4a/promote \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": {
  "flow": { "id": "flow_1a2b3c4d5e6f", "status": "active", "activeVersionId": "ver_...", "...": "..." },
  "version": { "id": "ver_...", "flowId": "flow_1a2b3c4d5e6f", "versionNumber": 1, "definition": { "...": "..." }, "checksum": "sha256...", "createdAt": "2026-07-02T14:02:00.000Z" }
} }

5. Get the webhook URL and test it¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/flow_1a2b3c4d5e6f/webhook \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": {
  "flowId": "flow_1a2b3c4d5e6f",
  "secret": "5f3a9c1e7b2d4f6a8c0e1b3d5f7a9c1e7b2d4f6a",
  "path": "/api/v1/webhooks/flow_1a2b3c4d5e6f/5f3a9c1e7b2d4f6a8c0e1b3d5f7a9c1e7b2d4f6a"
} }

Then fire it:

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/webhooks/flow_1a2b3c4d5e6f/5f3a9c1e7b2d4f6a8c0e1b3d5f7a9c1e7b2d4f6a" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace"}'

A 202 response with a runId means the flow ran — go check Monitoring Runs to see it.

Note on response shape. Most endpoint groups (including /flows, /drafts, /executions, /runs) return { "ok": true, "data": ... } on success. A couple of groups — /marketplace and /flow-designer (including Snap Studio) — return just { "data": ... } with no ok field. All errors, everywhere, look like { "ok": false, "error": { "code", "message", "details"? } }.

Best practices¶

Name flows by outcome ("Lead → Slack alert"), not by mechanism.
Keep flows small and single-purpose — one trigger, a short chain of actions.
Always validate before promoting; catching a missing_credential or schema_mismatch at draft time is much cheaper than debugging a failed run.
Test with a real webhook call right after promoting — see Editing Flows if you need to change something after.

FAQ¶

Can a flow have more than one action? Yes — actions run in order, one after another. Can a flow have more than one trigger? No, one trigger per flow today. What if I promote a draft and then want to change it? Create a new draft on the same flow — see Editing Flows; the old version stays in history.

If something goes wrong¶

If your flow doesn't seem to run at all after you've promoted it and called its webhook, see Flow not running.

Related: Snap Studio · Editing Flows · Flow Validation · Flow Templates