The whole hunk
from line 7, old and new numbered
/
lines
from line 7
77
88**POST** `/v1/dreams`
99
10Create a Dream
10Start an asynchronous job that uses past sessions to produce a reorganized version of a memory store and get back the dream to poll for the result.
1111
12By default the dream writes its result to a new memory store and doesn't change the input memory store. The response has `status` set to `pending` and an empty `outputs` array. Poll the dream until `status` is `completed`, `failed`, or `canceled`.
13
14See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#create-a-dream) to learn more about creating dreams.
15
1216## Headers
1317
1418- `"anthropic-beta": optional array of AnthropicBeta`
from line 117
113117
114118- `"anthropic-workspace-id": optional string`
115119
120 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).
121
122 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.
123
116124## Body parameters
117125
118126- `inputs: array of BetaDreamInput`
119127
128 The memory store and sessions for the dream to read, as exactly one `memory_store` entry and exactly one `sessions` entry.
129
120130 - `BetaDreamMemoryStoreInput object`
121131
122 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
132 The memory store that a dream reads, given as an entry in `inputs`.
123133
134 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.
135
124136 - `type: "memory_store"`
125137
126138 - `memory_store_id: string`
127139
140 The ID of the memory store for the dream to read (`memstore_...`).
141
142 The memory store must be in the same workspace as the dream and must not be archived.
143
128144 minLength: 1
129145
130146 - `BetaDreamSessionsInput object`
131147
132 Input session transcripts the dream reads.
148 The sessions that a dream reads, given as an entry in `inputs`.
133149
134150 - `type: "sessions"`
135151
136152 - `session_ids: array of string`
137153
154 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).
155
156 Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order.
157
158 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.
159
138160- `model: string or BetaDreamModelConfigParam`
139161
162 The model that runs a dream, given as a model ID or as an object with `id` and `speed`.
163
164 In the object form, `speed` can only be `standard`.
165
166 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists the supported models.
167
140168 - `string`
141169
142170 - `BetaDreamModelConfigParam object`
143171
144 Model identifier and configuration applied to every pipeline stage.
172 The object form of `model` in a request to create a dream.
145173
146174 - `id: string`
147175
148 Model identifier, e.g. "claude-opus-5". 1-256 characters.
176 The ID of the model to run the dream with.
149177
178 The ID can be 1 to 256 characters long.
179
180 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists the supported models.
181
150182 minLength: 1, maxLength: 256
151183
152184 - `speed: optional "standard" or "fast" or null`
from line 191
159191
160192- `instructions: optional string or null`
161193
194 Guidance that steers how the dream reads the sessions and organizes the output memory store, from 1 to 4,096 characters.
195
196 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#steer-with-instructions) for what kinds of instructions work well.
197
162198 minLength: 1, maxLength: 4096
163199
164200- `output_behavior: optional BetaOutputBehavior`
165201
202 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.
203
166204 - `BetaOutputBehaviorCreateNew object`
167205
168 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
206 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.
169207
208 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.
209
170210 - `type: "create_new"`
171211
172212 - `BetaOutputBehaviorUpdateExisting object`
173213
174 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
214 Write the result into the input memory store instead of a new memory store.
175215
216 The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error.
217
176218 - `type: "update_existing"`
177219
178220 - `memory_store_id: string`
179221
222 The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`.
223
180224 minLength: 1
181225
182226## Returns
from line 227
183227
184228- `BetaDream object`
185229
186 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
230 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.
187231
232 By default the dream writes its result to a new memory store and doesn't change the input memory store. With `output_behavior` set to `update_existing`, it writes its result into the input memory store instead. The Dreams API is in research preview, so this resource can still change.
233
234 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.
235
188236 - `type: "dream"`
189237
190238 - `id: string`
191239
240 The unique ID of the dream (`drm_...`).
241
192242 - `archived_at: string or null`
193243
194244 A timestamp in RFC 3339 format
from line 263
213263
214264 - `type: string`
215265
266 A code for why the dream failed, such as `timeout` or `internal_error`.
267
268 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.
269
216270 - `message: string`
217271
272 A human-readable explanation of why the dream failed.
273
218274 - `inputs: array of BetaDreamInput`
219275
276 The sources that the dream reads, from the request that created it.
277
220278 - `BetaDreamMemoryStoreInput object`
221279
222 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
280 The memory store that a dream reads, given as an entry in `inputs`.
223281
282 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.
283
224284 - `type: "memory_store"`
225285
226286 - `memory_store_id: string`
227287
288 The ID of the memory store for the dream to read (`memstore_...`).
289
290 The memory store must be in the same workspace as the dream and must not be archived.
291
228292 minLength: 1
229293
230294 - `BetaDreamSessionsInput object`
231295
232 Input session transcripts the dream reads.
296 The sessions that a dream reads, given as an entry in `inputs`.
233297
234298 - `type: "sessions"`
235299
236300 - `session_ids: array of string`
237301
302 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).
303
304 Give 1 to 100 IDs, with no duplicates. Each session must be in the same workspace as the dream. Responses list the IDs in sorted order.
305
306 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.
307
238308 - `instructions: string or null`
239309
310 The guidance given when the dream was created, or `null` if none was given.
311
240312 - `model: BetaDreamModelConfig`
241313
242 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.
314 The model that runs a dream, from the request that created it.
243315
316 The dream uses this model for all of its work. The response always gives the model as an object, even if the request gave only a model ID.
317
244318 - `id: string`
245319
246 Model identifier, e.g. "claude-opus-5". 1-256 characters.
320 The ID of the model that runs the dream, as given in the request that created it.
247321
248322 minLength: 1, maxLength: 256
249323
from line 331
257331
258332 - `output_behavior: BetaOutputBehavior`
259333
334 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.
335
260336 - `BetaOutputBehaviorCreateNew object`
261337
262 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
338 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.
263339
340 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.
341
264342 - `type: "create_new"`
265343
266344 - `BetaOutputBehaviorUpdateExisting object`
267345
268 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
346 Write the result into the input memory store instead of a new memory store.
269347
348 The credential must be allowed to write memory stores, or the request returns a 403 error. While another `update_existing` dream on the same memory store hasn't fully stopped, the request returns a 409 error.
349
270350 - `type: "update_existing"`
271351
272352 - `memory_store_id: string`
273353
354 The ID of the memory store for the dream to write its result to (`memstore_...`). It must be the memory store in the `memory_store` entry of `inputs`.
355
274356 minLength: 1
275357
276358 - `outputs: array of BetaDreamOutput`
277359
360 The memory store that holds the dream's result, as a one-item array, or an empty array until the dream records that memory store.
361
362 The array is empty while the dream is `pending` and for a short time after it starts `running`. It can stay empty if the dream fails or is canceled before then. The memory store holds the complete result only once `status` is `completed`.
363
364 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.
365
278366 - `type: "memory_store"`
279367
280368 - `memory_store_id: string`
281369
370 The ID of the memory store that the dream writes its result to (`memstore_...`).
371
372 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.
373
282374 - `session_id: string or null`
283375
376 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.
377
378 Stream that session's events to follow what the dream reads and writes.
379
380 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.
381
284382 - `status: BetaDreamStatus`
285383
286 Lifecycle status of a Dream.
384 Where a dream is in its lifecycle.
287385
386 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.
387
388 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.
389
288390 - `"pending"`
289391
392 The dream is waiting to start and hasn't read its inputs yet.
393
394 `outputs` is empty and every `usage` count is zero.
395
290396 - `"running"`
291397
398 The dream is reading its inputs and writing its result.
399
400 `usage` updates while the dream has this status.
401
292402 - `"completed"`
293403
404 The dream finished and its output memory store holds the complete result.
405
294406 - `"failed"`
295407
408 The dream stopped with an error, which `error` describes.
409
410 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.
411
296412 - `"canceled"`
297413
414 A cancel request stopped the dream before it reached `completed` or `failed`.
415
416 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.
417
298418 - `usage: BetaDreamUsage`
299419
300 Cumulative token usage for the dream across every pipeline stage.
420 The tokens that a dream has used so far.
301421
422 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.
423
424 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#billing) for how dreams are billed. See the [prompt caching guide](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) for how the input token counts add up.
425
302426 - `cache_creation_input_tokens: number`
303427
304 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
428 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.
305429
306430 format: int32
307431
308432 - `cache_read_input_tokens: number`
309433
310 Total tokens read from prompt cache.
434 The dream's input tokens that were read from the prompt cache.
311435
312436 format: int32
313437
314438 - `input_tokens: number`
315439
316 Total uncached input tokens consumed across every pipeline stage.
440 The dream's input tokens that weren't read from or written to the prompt cache.
317441
318442 format: int32
319443
320444 - `output_tokens: number`
321445
322 Total output tokens generated across every pipeline stage.
446 The tokens that the model generated for the dream.
323447
324448 format: int32
325449