---
title: "Post Ai Builder Turn"
method: POST
path: "/v1/flow_automation/ai_builder/turn"
tags: ["flow_automation", "flow_automation_ai_builder"]
---

# Post Ai Builder Turn

`POST /v1/flow_automation/ai_builder/turn`

## Request

- Base URL: `https://api.linktodm.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.linktodm.com/v1/flow_automation/ai_builder/turn`
- Auth: HTTP bearer

Run one user turn as a Server-Sent Events stream.

Response body is `text/event-stream`. Each event is one JSON object
on a `data:` line, with a blank line terminator. The client parses
`event` to dispatch (see `schemas.ChatTurnEvent`).

When `payload.flow_automation_id` (saved flow) or `payload.draft_key`
(unsaved /create flow) is supplied, the turn is persisted to
`FlowAiChatSession` for cross-reload continuity.

Gated by the plan token quota: free users are blocked, Pro/Pro+ have a
monthly token budget. The check runs BEFORE the stream so a blocked
user gets a clean 402 (not a half-streamed error); test/exempt users
skip it. Usage is recorded inside `run_turn` after the turn runs.

## Request body

- ChatTurnPayload: User-side payload for `POST /turn`. Carries the new user message plus everything the server needs to run a stateless turn: the current graph (so Claude sees what's already built) and the prior conversation history (so multi-turn refinement works).
  - `message` string, required
  - `nodes` object[]
  - `edges` object[]
  - `history` object[]
  - `media_source` string, nullable
  - `flow_automation_id` integer, nullable
  - `draft_key` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/linktodm/apis/salesmorph.md) - [All operations](https://skmtc.dev/linktodm/apis/salesmorph/llms.txt) - [OpenAPI document](https://skmtc.dev/linktodm/apis/salesmorph/revisions/4af0ad5dbe92?raw)