--- title: "Create Human Conversation Session" method: POST path: "/v1/teams/{team_id}/sessions" tags: ["agent runtime"] --- # Create Human Conversation Session `POST /v1/teams/{team_id}/sessions` Create an empty attached-human room without starting model work. A desk used to manufacture its session by running a private kickoff. If the owner pressed Talk while that model was still working, their first spoken delegation queued behind setup work they never asked for. The room is durable state; opening it is not an agent turn. ## Path parameters - `team_id` string, uuid, required ## Headers - `authorization` string, nullable - `x-darwin-token` string, nullable ## Request body - CreateHumanConversationSessionRequest — Open the durable room before its first real human turn. - `client_session_id` string, uuid, required - `client_context` HumanConversationContext, required — Client-observed facts for a human attached to an ordinary run. These facts shape communication, never authority. The server adds the communication contract and message clocks after accepting the turn. - `channel` 'web_chat' - `modality` 'text' | 'voice', nullable - `transport` 'browser_webrtc', nullable - `provider_session_id` string, nullable - `surface` string, required - `device` 'phone' | 'tablet' | 'desktop' | 'unknown' - `platform` string, nullable - `viewport_width` integer, nullable - `viewport_height` integer, nullable - `touch` boolean, nullable - `locale` string, nullable - `time_zone` string, nullable - `message_visibility` 'human' | 'private' - `delivery` 'steer' | 'insert' | 'queue', nullable - `audience_attached` boolean - `answer_pressed` boolean - `replying_to` ReplyingTo — WHICH MESSAGE THIS TURN IS AN ANSWER TO, when the person said so. The chat has had the whole Telegram-shaped reply gesture since it shipped — pick a bubble, it rides above the composer, and the sent message quotes it — and `useHarnessTurn` has been posting `client_context.replying_to` the whole time. Nothing on this side declared the field, so pydantic dropped it at the door on every turn: the one fact that disambiguates a short answer was collected, transmitted, and thrown away. The receipt (owner, 2026-08-18, `channel:marketing`). He replied INLINE to his own "Build me Google Ads board please" with the word "follow up", and the desk answered "Checking the outbound targets and previous outreach right now" — reading "follow up" as chase-the-leads rather than as what the quote made unambiguous. Same failure the blue lane fixed in `thread_context.py`, one surface over: Apple's pointer and this one both name the message, and both are worthless if the transport strips them. Bounds match what the composer can actually build (`QUOTE_LIMIT = 140`, plus room for the ellipsis) — this is an OBSERVATION from a client, so it is sized here rather than trusted. - `id` string, required - `from` string - `excerpt` string - `looking_at` Looking — WHERE THE PERSON IS STANDING while they type, in their own screen's words. THE BUG THIS FIXES IS THE `ReplyingTo` BUG, TWICE OVER. The shell has been posting `client_context.from_screen` and `client_context.about` from every generated screen's send button since that path shipped, and this model declared neither — so pydantic dropped both at the door on every turn, the same silent discard that made "follow up" unanswerable. A field the client sends and the server does not name is not context; it is bandwidth. IT IS THE BREADCRUMB, NOT THE PATH. `label` is what their screen actually shows them — "Front Desk › Calls › Robert Liu" — because that is the phrase they would use if asked what they were looking at, and it is the only form in which "the second one" resolves. `ref` rides alongside so the desk can OPEN the same thing instead of only naming it: they answer different questions and neither substitutes for the other. `spot` is a heading and a rough depth, never a pixel offset. A person can be answered about "under 'What we agreed'"; nobody can be answered about 812. Sized here rather than trusted, like every other client observation. - `label` string, required - `kind` 'conversation' | 'place' | 'screen' | 'record' | 'website' - `ref` string, nullable - `spot` string, nullable - `seconds` integer, nullable - `trail` Looking[], nullable - `label` string, required - `kind` 'conversation' | 'place' | 'screen' | 'record' | 'website' - `ref` string, nullable - `spot` string, nullable - `seconds` integer, nullable - `from_screen` string, nullable - `about` string, nullable - `interaction` 'agent_action' | 'screen_next', nullable - `control_key` string, nullable - `again` boolean - `resume_existing` boolean ## Response `201` Successful Response - object ## Other responses - `422` — Validation Error ## Changes > 32 revisions in range; 1 not diffed. - **2026-09-26** `faea4a09e09c` — 2 info - added the new optional request property `client_context/again` - added the new optional request property `client_context/answer_pressed` - **2026-09-14** `afcec8c2ed64` — 2 info - the `delivery` request property default value `steer` was added - added the new `steer` enum value to the request property `client_context/delivery/anyOf[subschema #1]/` - **2026-09-12** `c1ddc6c809d9` — 2 info - added the new optional request property `client_context/delivery` - added the new optional request property `client_context/provider_session_id` - **2026-09-11** `79b0c0f35170` — 1 info - added the new optional request property `resume_existing` - **2026-09-02** `032c0f4e1565` — 1 info - added the new optional request property `client_context/control_key` [Change history](https://skmtc.dev/stormy/apis/stormy-control-plane/changes/v1/teams/:team_id/sessions/post.md) --- [API](https://skmtc.dev/stormy/apis/stormy-control-plane.md) · [All operations](https://skmtc.dev/stormy/apis/stormy-control-plane/llms.txt) · [OpenAPI document](https://skmtc.dev/stormy/apis/stormy-control-plane/revisions/b09e3c4ee2af?raw)