SarufiSarufi Docs
View SiteDocs

Flows

Create and manage conversation flows and meta flows for a chatbot.

List Flows

Returns all flows belonging to a chatbot.

GET /api/dev/v1/chatbots/{chatbot_id}/flows
Authorization: Bearer <api-key>
curl -X GET https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

{
  "items": [
    {
      "id": "01JNA...",
      "chatbot_id": "01JMXYZ...",
      "name": "Main Conversation Flow",
      "type": "conversation",
      "status": "published",
      "created_at": "2026-01-20T08:00:00Z"
    }
  ],
  "total": 2
}

Create Flow

Creates a new flow for the specified chatbot.

POST /api/dev/v1/chatbots/{chatbot_id}/flows
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringyesDisplay name for the flow.
typestringyesFlow type: conversation (state-machine) or meta (WhatsApp UI Flows).
flowobjectnoInitial flow definition JSON. If omitted, a blank flow is created.
curl -X POST https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Flow",
    "type": "conversation"
  }'

Response - 201 Created

{
  "id": "01JNA456...",
  "chatbot_id": "01JMXYZ123...",
  "name": "Onboarding Flow",
  "type": "conversation",
  "status": "draft",
  "flow": {},
  "created_at": "2026-02-05T14:00:00Z",
  "updated_at": null
}

Get Flow

Retrieves a specific flow by ID including its full flow definition.

GET /api/dev/v1/chatbots/{chatbot_id}/flows/{flow_id}
Authorization: Bearer <api-key>
curl -X GET https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows/<flow-id> \
  -H "Authorization: Bearer <your-api-key>"

Update Flow

Updates a flow's name or its flow definition JSON.

PATCH /api/dev/v1/chatbots/{chatbot_id}/flows/{flow_id}
Authorization: Bearer <api-key>
Content-Type: application/json

Request Body (all fields optional)

FieldTypeDescription
namestringNew display name.
flowobjectUpdated flow definition JSON. Replaces the existing definition entirely.
curl -X PATCH https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows/<flow-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Onboarding Flow",
    "flow": { "states": [] }
  }'

Validate Flow

Runs backend validation on the flow definition and returns any errors or warnings. Does not change the flow's status.

POST /api/dev/v1/chatbots/{chatbot_id}/flows/{flow_id}/validate
Authorization: Bearer <api-key>
curl -X POST https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows/<flow-id>/validate \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "states.greeting.transitions",
      "message": "No fallback transition defined - users may get stuck."
    }
  ]
}

Validate before publishing

Always validate a flow before publishing. The publish endpoint will reject flows with errors.

Publish Flow

Publishes a validated flow, making it live for end users.

POST /api/dev/v1/chatbots/{chatbot_id}/flows/{flow_id}/publish
Authorization: Bearer <api-key>
curl -X POST https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows/<flow-id>/publish \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

{
  "id": "01JNA456...",
  "status": "published",
  "published_at": "2026-02-10T09:15:00Z"
}

Delete Flow

Permanently deletes a flow. Published flows can still be deleted - active conversations using that flow will not receive new messages.

DELETE /api/dev/v1/chatbots/{chatbot_id}/flows/{flow_id}
Authorization: Bearer <api-key>
curl -X DELETE https://developers.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/flows/<flow-id> \
  -H "Authorization: Bearer <your-api-key>"

Response - 204 No Content

Flow Object

FieldTypeDescription
idstringFlow ULID.
chatbot_idstringParent chatbot ID.
namestringFlow display name.
typestringconversation or meta.
statusstringdraft or published.
flowobjectThe flow definition JSON (states, transitions, screens, etc.).
created_atstringCreation timestamp.
updated_atstringLast update timestamp.

Chatbots

Create, list, retrieve, update, and delete chatbots in your workspace.

How Flows Work

Understand the flow system — states, transitions, variables, and action types — and how the conversation engine uses them to drive a chat.

On this page

List FlowsCreate FlowGet FlowUpdate FlowValidate FlowPublish FlowDelete FlowFlow Object