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.

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".

Get dream diary

GET /api/openclaw/dreams

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

Response

{
  "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

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

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

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)

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.

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

{
  "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.