Conversations
What this lets you do
Keep image work in a persistent conversation and continue it across multiple turns.What you need
- A server-side DreamLayer key
- A
conversation_idfrom thestartedevent of an earlier execution - A new idempotency key for each new logical turn
Steps
1. Save the conversation ID
The firstPOST /v1/execute returns conversation_id and execution_id in the started event. Persist both opaque IDs.
2. Continue after a question
If the stream emitsquestion and ends with done: needs_input, send a new request with the returned conversation ID:
3. Read the question you have to answer
GET /v1/executions/{execution_id} returns the outstanding question, so a client that reconnected, or never held the stream, can still answer:
question is null whenever nothing is outstanding, and that includes an execution you have already answered. Answering creates a NEW execution and does not move the old one: the execution that asked stays at status: needs_input for the rest of its life, and reports question: null once its question has been answered. So needs_input with a null question means “answered and superseded”, not “waiting”. Follow the execution ID returned by the answer, not the one that asked. A non-null question is the only reliable signal that a turn is still waiting for you.
When requires_asset is true the answer must carry an image as well as text:
input_asset_id is refused with a 422 whose details name the field:
POST /v1/executions/{execution_id}/cancel ends the execution and clears the way for a new turn. To avoid the round trip entirely, name the operation on the original request: a named operation is never reinterpreted and never asks a question.
4. List or delete conversations
GET /v1/conversationslists recent conversations owned by the key’s account.DELETE /v1/conversations/{conversation_id}deletes a terminal owned conversation.
Confirm it worked
The next execution uses the sameconversation_id and produces a new durable turn. V1 executes one workflow node per turn.
Common errors
404: the conversation does not exist for the authenticated account.409: read canonical state before continuing a non-terminal execution. Answering when no question is outstanding returns409withdetailsnamingconversation_id.422: the answer is missing something the question requires. Readerror.details.field.- A deleted conversation cannot accept another turn.