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

# Create Dream

> Trigger an asynchronous memory consolidation job.

`POST /api/v1/cloud/dreams`

Creates a Dream that asynchronously consolidates the specified Memory Store. Returns a [Dream object](/cloud-agents/api/dreams/schemas#dream-object).

## Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <PAT>`     |
| `Content-Type`  | Yes      | `application/json` |

## Request body

| Field          | Type   | Required | Description                                                                                       |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `inputs`       | array  | Yes      | Input list. Must include one `memory_store` type input; optionally include `sessions` type inputs |
| `model`        | string | No       | Model selection: `auto` (default), `lite`, `ultimate`                                             |
| `instructions` | string | No       | Custom consolidation instructions, max 4096 characters                                            |

### inputs elements

| Field             | Type   | Description                                           |
| ----------------- | ------ | ----------------------------------------------------- |
| `type`            | string | `"memory_store"` or `"sessions"`                      |
| `memory_store_id` | string | Required when type is `memory_store`                  |
| `session_ids`     | array  | Required when type is `sessions`, max 100 Session IDs |

## Example request

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/cloud/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" },
      { "type": "sessions", "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"] }
    ],
    "model": "auto",
    "instructions": "Focus on user preferences for code style"
  }'
```

## Example response

**HTTP 201 Created**

```json theme={null}
{
  "id": "drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9",
  "type": "dream",
  "status": "pending",
  "inputs": [
    { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" },
    { "type": "sessions", "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"] }
  ],
  "outputs": [],
  "model": { "id": "auto" },
  "instructions": "Focus on user preferences for code style",
  "session_id": null,
  "usage": { "input_tokens": 0, "output_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0 },
  "error": null,
  "created_at": "2026-06-15T10:00:00Z",
  "ended_at": null,
  "archived_at": null
}
```

## Errors

| HTTP | Type                    | Trigger                                                                                                                        |
| ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 400  | `invalid_request_error` | Empty inputs, missing memory\_store input, duplicate memory\_store, sessions exceeds 100, invalid model, instructions too long |
| 401  | `authentication_error`  | Missing or invalid authentication token                                                                                        |
| 404  | `not_found_error`       | Referenced Memory Store does not exist or is inaccessible                                                                      |
| 409  | `invalid_request_error` | User already has an active Dream (pending or running)                                                                          |

See [Error Reference](/cloud-agents/api/conventions/errors) for the full error envelope.