---
title: "Create Flow draft"
method: POST
path: "/api/v1/flows"
tags: ["flows"]
---

# Create Flow draft

`POST /api/v1/flows`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/flows`
- Auth: HTTP bearer

Create a WhatsApp Flow draft from a definition in Blueticked's builder dialect.

`definition` is Blueticked's builder dialect, not raw Meta Flow JSON: `{ version, screens: [...] }` where each screen is `{ id, title, terminal?, layout: { type: "SingleColumnLayout", children: [...] } }`. Screen ids use letters, digits and underscores.

Supported component types: TextInput, TextArea, DatePicker, CalendarPicker, Dropdown, RadioButtonsGroup, CheckboxGroup, ChipsSelector, OptIn, PhotoPicker, DocumentPicker, Image, TextHeading, TextSubheading, TextBody, TextCaption, RichText, EmbeddedLink, NavigationList, If, Switch and Footer (an explicit Form wrapper is also accepted). Anything else (e.g. Meta-only DateTimePicker or ImageCarousel) is rejected with `400 validation_failed` at create/update time.

Input components carry `name`, `label` and optional `required`; choice fields take `data-source` as a static `[{ id, title }]` list (or a `${data.key}` webhook binding on dynamic forms); each screen ends in a Footer whose `on-click-action.name` is `complete` (terminal screen), `navigate` or `data_exchange`.

On publish the stored dialect is transformed to Meta Flow JSON 7.3: the wire version is stamped, screens are wrapped in a Form, and the complete/navigate payload mappings Meta requires are generated, so never paste Meta Flow JSON here. Deeper rules (label caps, footer/payload rules) are checked at publish with friendly errors.

Omit `definition` (or send `{}`) to create a blank draft and fill it in via PATCH or the Flow builder UI.

The flow is returned flat (fields at the top level, the full serializer), matching GET /api/v1/flows/{id}.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string, required
  - `description` string, nullable
  - `definition` union
    - object
    - object
      - `version` string
      - `data_api_version` string
      - `routing_model` object
      - `screens` object[], required
        - `id` string, required
        - `title` string, required
        - `terminal` boolean
        - `data` object
        - `layout` object, required
          - `type` 'SingleColumnLayout', required
          - `children` object[], required
            - `type` 'TextInput' | 'TextArea' | 'DatePicker' | 'CalendarPicker' | 'Dropdown' | 'RadioButtonsGroup' | 'CheckboxGroup' | 'ChipsSelector' | 'OptIn' | 'PhotoPicker' | 'DocumentPicker' | 'Image' | 'TextHeading' | 'TextSubheading' | 'TextBody' | 'TextCaption' | 'RichText' | 'EmbeddedLink' | 'NavigationList' | 'Footer' | 'Form' | 'If' | 'Switch', required
  - `preset_id` string, nullable
  - `business_id` string, uuid, nullable

## Response `201`

Success

- object
  - `id` string, uuid, required
  - `business_id` string, uuid, nullable, required
  - `name` string, required
  - `description` string, nullable, required
  - `status` 'draft' | 'published' | 'deprecated', required
  - `preset_id` string, nullable, required
  - `meta_flow_id` string, nullable, required
  - `meta_flow_version` number, nullable, required
  - `definition` object, required
  - `public_key` string, nullable, required
  - `last_synced_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)