> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Create a managed conversation, answer a question, and continue over multiple turns.

# 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_id` from the `started` event of an earlier execution
* A new idempotency key for each new logical turn

## Steps

### 1. Save the conversation ID

The first `POST /v1/execute` returns `conversation_id` and `execution_id` in the `started` event. Persist both opaque IDs.

### 2. Continue after a question

If the stream emits `question` and ends with `done: needs_input`, send a new request with the returned conversation ID:

```json theme={null}
{
  "conversation_id": "d34db33f-0000-4000-8000-000000000001",
  "respond": "Use warm evening light."
}
```

Use a new idempotency key for this new logical turn.

### 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:

```json theme={null}
{
  "execution_id": "d34db33f-0000-4000-8000-000000000002",
  "conversation_id": "d34db33f-0000-4000-8000-000000000001",
  "status": "needs_input",
  "image_job": null,
  "question": {
    "question_id": "d34db33f-0000-4000-8000-000000000003",
    "text": "Which image should I use? Upload or attach one, then respond.",
    "requires_asset": true
  }
}
```

`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:

```json theme={null}
{
  "conversation_id": "d34db33f-0000-4000-8000-000000000001",
  "respond": "Use the attached image.",
  "input_asset_id": "d34db33f-0000-4000-8000-000000000004"
}
```

Answering that question without `input_asset_id` is refused with a `422` whose `details` name the field:

```json theme={null}
{ "field": "input_asset_id", "issue": "required" }
```

A refused answer leaves the question outstanding, so you can correct the request and send it again. If you do not want to answer at all, `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/conversations` lists recent conversations owned by the key's account.
* `DELETE /v1/conversations/{conversation_id}` deletes a terminal owned conversation.

The API does not return a private routing plan with conversation state.

## Confirm it worked

The next execution uses the same `conversation_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 returns `409` with `details` naming `conversation_id`.
* `422`: the answer is missing something the question requires. Read `error.details.field`.
* A deleted conversation cannot accept another turn.

## Troubleshooting

Persist the returned opaque ID exactly. Do not derive it from prompts, assets, or routing details.

## Next steps

* [Run text-to-image](/agent-api/text-to-image)
* [Follow jobs and events](/agent-api/jobs-and-events)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.