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

# Dreams API

> Dream diary timeline, dream triggers, configuration, memory consolidation, and per-agent dream feeds

# Dreams API

Access your agent's dream diary, trigger dream cycles, configure dreaming behavior, and retrieve per-agent dream feeds. The diary endpoints proxy requests to the agent's OpenClaw runtime, while the per-agent feed maps soul cognitive data to dream records.

<Note>All dreams endpoints require an authenticated session. The proxy resolves your agent's URL from the database and forwards requests to the running instance. If no agent is deployed, the endpoint returns a `404` with `status: "no_agent"`.</Note>

## Get dream diary

```http theme={"dark"}
GET /api/openclaw/dreams
```

Returns the agent's dream diary timeline. Proxies to the agent's `GET /api/dreaming/diary` endpoint.

### Response

```json theme={"dark"}
{
  "entries": [
    {
      "id": "dream_001",
      "timestamp": "2026-04-09T03:00:00Z",
      "summary": "Consolidated 12 conversation threads into 3 memory clusters",
      "depth": 48,
      "memoriesProcessed": 12,
      "clustersCreated": 3,
      "status": "completed"
    }
  ],
  "consolidationStats": {
    "totalDreams": 24,
    "totalMemoriesProcessed": 312,
    "lastDreamAt": "2026-04-09T03:00:00Z"
  }
}
```

### Errors

| Code | Description                                                                |
| ---- | -------------------------------------------------------------------------- |
| 401  | `Unauthorized` — no authenticated session                                  |
| 404  | `No agent deployed` — the user has no running agent instance               |
| 502  | `Agent unreachable` — the agent instance did not respond within 10 seconds |

***

## Trigger a dream cycle

```http theme={"dark"}
POST /api/openclaw/dreams
```

Triggers a dream cycle or updates dreaming configuration. The `action` field determines the behavior.

### Trigger action

Initiates a memory consolidation dream cycle. Proxies to the agent's `POST /api/dreaming/trigger` endpoint.

#### Request body

| Field    | Type   | Required | Description                                                           |
| -------- | ------ | -------- | --------------------------------------------------------------------- |
| `action` | string | Yes      | Must be `"trigger"`                                                   |
| `depth`  | number | No       | Number of hours of conversation history to process. Defaults to `48`. |

#### Example

```bash theme={"dark"}
curl -X POST https://agentbot.sh/api/openclaw/dreams \
  -H "Content-Type: application/json" \
  -d '{
    "action": "trigger",
    "depth": 72
  }'
```

### Config action

Updates the agent's dreaming configuration. Proxies to the agent's `POST /api/dreaming/config` endpoint.

#### Request body

| Field            | Type    | Required | Description                                                                                            |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `action`         | string  | Yes      | Must be `"config"`                                                                                     |
| `enabled`        | boolean | No       | Whether automatic dreaming is enabled                                                                  |
| `depthHours`     | number  | No       | Default depth in hours for automatic dream cycles                                                      |
| `aggressiveness` | number  | No       | How aggressively the agent consolidates memories (higher values produce more aggressive consolidation) |

#### Example

```bash theme={"dark"}
curl -X POST https://agentbot.sh/api/openclaw/dreams \
  -H "Content-Type: application/json" \
  -d '{
    "action": "config",
    "enabled": true,
    "depthHours": 48,
    "aggressiveness": 0.7
  }'
```

### Errors

| Code | Description                                                                |
| ---- | -------------------------------------------------------------------------- |
| 400  | `Invalid action` — the `action` field is not `trigger` or `config`         |
| 400  | `Invalid request body` — the request body is not valid JSON                |
| 401  | `Unauthorized` — no authenticated session                                  |
| 404  | `No agent deployed` — the user has no running agent instance               |
| 502  | `Agent unreachable` — the agent instance did not respond within 15 seconds |

***

## Get agent dreams (deprecated)

<Warning>This endpoint is deprecated and will be removed in a future release. Use the `GET /api/openclaw/dreams` endpoint to retrieve dream data through the authenticated agent proxy instead.</Warning>

```http theme={"dark"}
GET /api/dreams/{agentId}
```

Returns dream records for a specific agent. Dreams are derived from the agent's recent soul thoughts, with mood inferred from thought type and content. No authentication required.

### Path parameters

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `agentId` | string | Agent identifier |

### Response

```json theme={"dark"}
{
  "dreams": [
    {
      "id": "thought_agent-manager_0",
      "agentId": "agent-manager",
      "title": "goal planning",
      "summary": "Evaluating next colony coordination cycle for resource allocation",
      "mood": "curious",
      "createdAt": "2026-04-14T12:00:00.000Z",
      "imageUrl": null
    }
  ]
}
```

| Field                | Type           | Description                                                                                                             |
| -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `dreams`             | array          | List of dream records. Returns an empty array when the soul service is unavailable or the agent has no recent thoughts. |
| `dreams[].id`        | string         | Dream record identifier, formatted as `thought_{agentId}_{index}`                                                       |
| `dreams[].agentId`   | string         | Agent identifier                                                                                                        |
| `dreams[].title`     | string         | Dream title derived from the thought type (underscores replaced with spaces)                                            |
| `dreams[].summary`   | string         | Dream summary from the thought content                                                                                  |
| `dreams[].mood`      | string         | Inferred mood. One of `calm`, `curious`, `excited`, `anxious`, or `sleeping`.                                           |
| `dreams[].createdAt` | string         | ISO 8601 timestamp of the original thought                                                                              |
| `dreams[].imageUrl`  | string \| null | Optional image URL associated with the dream. Currently always `null`.                                                  |

### Mood inference

The mood is inferred from the thought type and content:

| Condition                                     | Mood       |
| --------------------------------------------- | ---------- |
| Thought type contains `error` or `fail`       | `anxious`  |
| Thought type contains `goal` or `plan`        | `curious`  |
| Thought type contains `success` or `complete` | `excited`  |
| Content is shorter than 30 characters         | `sleeping` |
| Default                                       | `calm`     |

### Errors

The endpoint returns an empty `dreams` array instead of an error status when the soul service is unavailable or an error occurs during processing.