---
title: "Create a flow and its first immutable version"
method: POST
path: "/api/flows"
tags: ["Flows"]
---

# Create a flow and its first immutable version

`POST /api/flows`

## Request

- Base URL: `https://api.wordis-bond.com`
- URL: `https://api.wordis-bond.com/api/flows`
- Auth: HTTP bearer

Compile a phone-system flow to the canonical Flow IR and save it as version 1. Each save is immutable and content-hashed — this is the version control.

## Request body

- object
  - `name` string, required
  - `language` string
  - `description` string
  - `suiteId` string: Test suite the regression gate runs against this flow.
  - `ir` FlowIR, required: The canonical, git-serializable representation of a phone-system flow. A discriminated node graph (prompt / menu / condition / agent / transfer / tool / hangup) plus flow metadata. Deterministic serialization → a stable content hash and a clean diff, so a flow can be version-controlled and regression-tested like source code. Extensible toward the migration surface — the same envelope hosts an imported vendor config and a hand-authored flow.
    - `schemaVersion` 1, required
    - `kind` 'voice_flow', required
    - `name` string, required
    - `language` string, required
    - `entry` string, required: Id of the node the call enters at.
    - `nodes` object[], required
      - `id` string, required
      - `type` 'prompt' | 'menu' | 'condition' | 'agent' | 'transfer' | 'tool' | 'hangup', required
      - `label` string
    - `metadata` object: Free-form; reserved keys `goal` and `persona` drive the regression scenario.
  - `note` string

## Response `201`

Created

- object
  - `data` object, required
  - `error` union, required
    - object
    - string

## Other responses

- `401`: Missing, invalid, or revoked credentials.
- `422`: The request body failed validation.

---

[API](https://skmtc.dev/wordis-bond/apis/word-is-bond-voice-agent-testing-api.md) · [All operations](https://skmtc.dev/wordis-bond/apis/word-is-bond-voice-agent-testing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wordis-bond/apis/word-is-bond-voice-agent-testing-api/revisions/66c2d5480d84?raw)