---
title: "Run a Bee Code software-development turn"
method: POST
path: "/bee/code/v1/turns"
---

# Run a Bee Code software-development turn

`POST /bee/code/v1/turns`

## Request

- Base URL: `https://api.bee.heossi.com`
- URL: `https://api.bee.heossi.com/bee/code/v1/turns`
- Auth: HTTP bearer

Versioned, structured NDJSON agent protocol for local IDE, CLI, and API clients. Tool calls, file deltas, approvals, progress, completion, and failure are machine events rather than assistant prose.

## Request body

- object
  - `protocol` 'bee.code.v1', required
  - `session_id` string, required
  - `run_id` string, uuid: Stable durable run identifier across every manager/tool cycle for one customer task.
  - `turn_id` string, required
  - `model` 'bee-cell' | 'bee-brood' | 'bee-comb' | 'bee-buzz' | 'bee-hive' | 'bee-swarm', required
  - `mode` 'manual' | 'plan' | 'edit' | 'auto', required
  - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultracode': Optional product effort level; omitted keeps the plane's default output budget.
  - `enable_thinking` boolean: Enable the selected model's explicit thinking mode. Requests are rejected when the model does not support it.
  - `request` string, required
  - `cursor` integer
  - `workspace` object, required
  - `transcript` unknown[], required
    - unknown
  - `client_tools` object[]: Bounded tools registered in the calling VS Code host, including MCP tools. Every invocation remains locally validated and approval-gated.
    - `name` string, required
    - `description` string, required
    - `input_schema` object, required
    - `tags` string[], required
  - `capabilities` object, required

## Response `200`

Ordered Bee Code event stream.

## Other responses

- `400`: Invalid Bee Code protocol request
- `401`: Missing or invalid API credential
- `402`: Hard plan allowance reached; upgrade required
- `403`: Model, scope, or authorised-security requirement denied
- `429`: Allowance or rate limit reached
- `503`: Entitled runtime or durable run store unavailable

---

[API](https://skmtc.dev/heossi/apis/bee-quantum-intelligence-developer-api.md) · [All operations](https://skmtc.dev/heossi/apis/bee-quantum-intelligence-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heossi/apis/bee-quantum-intelligence-developer-api/revisions/285f9cfc359b?raw)