api/beta/dreams / documentation change

The whole hunk

from line 9, old and new numbered

lines

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 9

1010**POST** `/v1/dreams`

1111

12Create a Dream

12Start 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.

14By 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`.

16See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#create-a-dream) to learn more about creating dreams.

1317

1418### Headers

1519

from line 119

115119

116120- `"anthropic-workspace-id": optional string`

117121

122 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

123

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

125

118126### Body parameters

119127

120128- `inputs: array of BetaDreamInput`

121129

130 The memory store and sessions for the dream to read, as exactly one `memory_store` entry and exactly one `sessions` entry.

131

122132 - `BetaDreamMemoryStoreInput object`

123133

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

134 The memory store that a dream reads, given as an entry in `inputs`.

135

136 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

125137

126138 - `type: "memory_store"`

127139

128140 - `memory_store_id: string`

129141

142 The ID of the memory store for the dream to read (`memstore_...`).

143

144 The memory store must be in the same workspace as the dream and must not be archived.

145

130146 minLength: 1

131147

132148 - `BetaDreamSessionsInput object`

133149

134 Input session transcripts the dream reads.

150 The sessions that a dream reads, given as an entry in `inputs`.

135151

136152 - `type: "sessions"`

137153

138154 - `session_ids: array of string`

139155

156 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

157

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

159

160 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

161

140162- `model: string or BetaDreamModelConfigParam`

141163

164 The model that runs a dream, given as a model ID or as an object with `id` and `speed`.

165

166 In the object form, `speed` can only be `standard`.

167

168 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists the supported models.

169

142170 - `string`

143171

144172 - `BetaDreamModelConfigParam object`

145173

146 Model identifier and configuration applied to every pipeline stage.

174 The object form of `model` in a request to create a dream.

147175

148176 - `id: string`

149177

150 Model identifier, e.g. "claude-opus-5". 1-256 characters.

178 The ID of the model to run the dream with.

179

180 The ID can be 1 to 256 characters long.

181

182 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists the supported models.

151183

152184 minLength: 1, maxLength: 256

153185

from line 193

161193

162194- `instructions: optional string or null`

163195

196 Guidance that steers how the dream reads the sessions and organizes the output memory store, from 1 to 4,096 characters.

197

198 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#steer-with-instructions) for what kinds of instructions work well.

199

164200 minLength: 1, maxLength: 4096

165201

166202- `output_behavior: optional BetaOutputBehavior`

167203

204 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

205

168206 - `BetaOutputBehaviorCreateNew object`

169207

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

208 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

209

210 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

171211

172212 - `type: "create_new"`

173213

174214 - `BetaOutputBehaviorUpdateExisting object`

175215

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

216 Write the result into the input memory store instead of a new memory store.

217

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

177219

178220 - `type: "update_existing"`

179221

180222 - `memory_store_id: string`

181223

224 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`.

225

182226 minLength: 1

183227

184228### Returns

185229

186230- `BetaDream object`

187231

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

232 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.

233

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

235

236 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.

189237

190238 - `type: "dream"`

191239

192240 - `id: string`

193241

242 The unique ID of the dream (`drm_...`).

243

194244 - `archived_at: string or null`

195245

196246 A timestamp in RFC 3339 format

from line 265

215265

216266 - `type: string`

217267

268 A code for why the dream failed, such as `timeout` or `internal_error`.

269

270 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

271

218272 - `message: string`

219273

274 A human-readable explanation of why the dream failed.

275

220276 - `inputs: array of BetaDreamInput`

221277

278 The sources that the dream reads, from the request that created it.

279

222280 - `BetaDreamMemoryStoreInput object`

223281

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

282 The memory store that a dream reads, given as an entry in `inputs`.

283

284 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

225285

226286 - `type: "memory_store"`

227287

228288 - `memory_store_id: string`

229289

290 The ID of the memory store for the dream to read (`memstore_...`).

291

292 The memory store must be in the same workspace as the dream and must not be archived.

293

230294 minLength: 1

231295

232296 - `BetaDreamSessionsInput object`

233297

234 Input session transcripts the dream reads.

298 The sessions that a dream reads, given as an entry in `inputs`.

235299

236300 - `type: "sessions"`

237301

238302 - `session_ids: array of string`

239303

304 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

305

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

307

308 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

309

240310 - `instructions: string or null`

241311

312 The guidance given when the dream was created, or `null` if none was given.

313

242314 - `model: BetaDreamModelConfig`

243315

244 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

316 The model that runs a dream, from the request that created it.

317

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

245319

246320 - `id: string`

247321

248 Model identifier, e.g. "claude-opus-5". 1-256 characters.

322 The ID of the model that runs the dream, as given in the request that created it.

249323

250324 minLength: 1, maxLength: 256

251325

from line 333

259333

260334 - `output_behavior: BetaOutputBehavior`

261335

336 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

337

262338 - `BetaOutputBehaviorCreateNew object`

263339

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

340 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

341

342 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

265343

266344 - `type: "create_new"`

267345

268346 - `BetaOutputBehaviorUpdateExisting object`

269347

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

348 Write the result into the input memory store instead of a new memory store.

349

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

271351

272352 - `type: "update_existing"`

273353

274354 - `memory_store_id: string`

275355

356 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`.

357

276358 minLength: 1

277359

278360 - `outputs: array of BetaDreamOutput`

279361

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

363

364 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`.

365

366 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

367

280368 - `type: "memory_store"`

281369

282370 - `memory_store_id: string`

283371

372 The ID of the memory store that the dream writes its result to (`memstore_...`).

373

374 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

375

284376 - `session_id: string or null`

285377

378 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

379

380 Stream that session's events to follow what the dream reads and writes.

381

382 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

383

286384 - `status: BetaDreamStatus`

287385

288 Lifecycle status of a Dream.

386 Where a dream is in its lifecycle.

387

388 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

389

390 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

289391

290392 - `"pending"`

291393

394 The dream is waiting to start and hasn't read its inputs yet.

395

396 `outputs` is empty and every `usage` count is zero.

397

292398 - `"running"`

293399

400 The dream is reading its inputs and writing its result.

401

402 `usage` updates while the dream has this status.

403

294404 - `"completed"`

295405

406 The dream finished and its output memory store holds the complete result.

407

296408 - `"failed"`

297409

410 The dream stopped with an error, which `error` describes.

411

412 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

413

298414 - `"canceled"`

299415

416 A cancel request stopped the dream before it reached `completed` or `failed`.

417

418 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

419

300420 - `usage: BetaDreamUsage`

301421

302 Cumulative token usage for the dream across every pipeline stage.

422 The tokens that a dream has used so far.

423

424 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

425

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

303427

304428 - `cache_creation_input_tokens: number`

305429

306 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

430 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

307431

308432 format: int32

309433

310434 - `cache_read_input_tokens: number`

311435

312 Total tokens read from prompt cache.

436 The dream's input tokens that were read from the prompt cache.

313437

314438 format: int32

315439

316440 - `input_tokens: number`

317441

318 Total uncached input tokens consumed across every pipeline stage.

442 The dream's input tokens that weren't read from or written to the prompt cache.

319443

320444 format: int32

321445

322446 - `output_tokens: number`

323447

324 Total output tokens generated across every pipeline stage.

448 The tokens that the model generated for the dream.

325449

326450 format: int32

327451

from line 516

392516

393517**GET** `/v1/dreams`

394518

395List Dreams

519List the dreams in the workspace, newest first.

520

521Archived dreams are left out unless `include_archived` is `true`.

522

523See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#list-dreams) for how to page through dreams.

396524

397525### Query parameters

398526

399527- `"created_at[gt]": optional string`

400528

401 Return dreams with `created_at` strictly after this timestamp (exclusive lower bound, RFC 3339). Unset applies no lower bound.

529 Return only dreams created after this time (exclusive), in RFC 3339.

402530

403531 format: date-time

404532

405533- `"created_at[lt]": optional string`

406534

407 Return dreams with `created_at` strictly before this timestamp (exclusive upper bound, RFC 3339). Unset applies no upper bound.

535 Return only dreams created before this time (exclusive), in RFC 3339.

408536

409537 format: date-time

410538

411539- `include_archived: optional boolean`

412540

413 Query parameter for include_archived

541 Whether to include archived dreams. Defaults to `false`.

414542

415543- `limit: optional number`

416544

417 Query parameter for limit

545 The maximum number of dreams to return, from 1 to 100. Defaults to 20.

418546

419547 format: int32

420548

421549- `page: optional string`

422550

423 Query parameter for page

551 The cursor for the page to return, taken from `next_page` in a previous response.

552

553 Leave it out to get the first page.

424554

425555- `statuses: optional array of BetaDreamStatus`

426556

427 Filter by lifecycle status. Repeat the parameter to match any of multiple statuses. Empty applies no status filter.

557 Return only dreams that have one of these statuses.

558

559 Repeat the parameter to give more than one status. Leave it out to return dreams of every status.

428560

429561 - `"pending"`

430562

563 The dream is waiting to start and hasn't read its inputs yet.

564

565 `outputs` is empty and every `usage` count is zero.

566

431567 - `"running"`

432568

569 The dream is reading its inputs and writing its result.

570

571 `usage` updates while the dream has this status.

572

433573 - `"completed"`

434574

575 The dream finished and its output memory store holds the complete result.

576

435577 - `"failed"`

436578

579 The dream stopped with an error, which `error` describes.

580

581 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

582

437583 - `"canceled"`

438584

585 A cancel request stopped the dream before it reached `completed` or `failed`.

586

587 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

588

439589### Headers

440590

441591- `"anthropic-beta": optional array of AnthropicBeta`

from line 690

540690

541691- `"anthropic-workspace-id": optional string`

542692

693 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

694

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

696

543697### Returns

544698

545699- `data: array of BetaDream`

546700

701 The dreams on this page, newest first.

702

547703 - `type: "dream"`

548704

549705 - `id: string`

550706

707 The unique ID of the dream (`drm_...`).

708

551709 - `archived_at: string or null`

552710

553711 A timestamp in RFC 3339 format

from line 730

572730

573731 - `type: string`

574732

733 A code for why the dream failed, such as `timeout` or `internal_error`.

734

735 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

736

575737 - `message: string`

576738

739 A human-readable explanation of why the dream failed.

740

577741 - `inputs: array of BetaDreamInput`

578742

743 The sources that the dream reads, from the request that created it.

744

579745 - `BetaDreamMemoryStoreInput object`

580746

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

747 The memory store that a dream reads, given as an entry in `inputs`.

748

749 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

582750

583751 - `type: "memory_store"`

584752

585753 - `memory_store_id: string`

586754

755 The ID of the memory store for the dream to read (`memstore_...`).

756

757 The memory store must be in the same workspace as the dream and must not be archived.

758

587759 minLength: 1

588760

589761 - `BetaDreamSessionsInput object`

590762

591 Input session transcripts the dream reads.

763 The sessions that a dream reads, given as an entry in `inputs`.

592764

593765 - `type: "sessions"`

594766

595767 - `session_ids: array of string`

596768

769 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

770

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

772

773 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

774

597775 - `instructions: string or null`

598776

777 The guidance given when the dream was created, or `null` if none was given.

778

599779 - `model: BetaDreamModelConfig`

600780

601 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

781 The model that runs a dream, from the request that created it.

782

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

602784

603785 - `id: string`

604786

605 Model identifier, e.g. "claude-opus-5". 1-256 characters.

787 The ID of the model that runs the dream, as given in the request that created it.

606788

607789 minLength: 1, maxLength: 256

608790

from line 798

616798

617799 - `output_behavior: BetaOutputBehavior`

618800

801 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

802

619803 - `BetaOutputBehaviorCreateNew object`

620804

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

805 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

806

807 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

622808

623809 - `type: "create_new"`

624810

625811 - `BetaOutputBehaviorUpdateExisting object`

626812

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

813 Write the result into the input memory store instead of a new memory store.

814

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

628816

629817 - `type: "update_existing"`

630818

631819 - `memory_store_id: string`

632820

821 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`.

822

633823 minLength: 1

634824

635825 - `outputs: array of BetaDreamOutput`

636826

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

828

829 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`.

830

831 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

832

637833 - `type: "memory_store"`

638834

639835 - `memory_store_id: string`

640836

837 The ID of the memory store that the dream writes its result to (`memstore_...`).

838

839 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

840

641841 - `session_id: string or null`

642842

843 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

844

845 Stream that session's events to follow what the dream reads and writes.

846

847 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

848

643849 - `status: BetaDreamStatus`

644850

645 Lifecycle status of a Dream.

851 Where a dream is in its lifecycle.

852

853 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

854

855 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

646856

647857 - `"pending"`

648858

859 The dream is waiting to start and hasn't read its inputs yet.

860

861 `outputs` is empty and every `usage` count is zero.

862

649863 - `"running"`

650864

865 The dream is reading its inputs and writing its result.

866

867 `usage` updates while the dream has this status.

868

651869 - `"completed"`

652870

871 The dream finished and its output memory store holds the complete result.

872

653873 - `"failed"`

654874

875 The dream stopped with an error, which `error` describes.

876

877 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

878

655879 - `"canceled"`

656880

881 A cancel request stopped the dream before it reached `completed` or `failed`.

882

883 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

884

657885 - `usage: BetaDreamUsage`

658886

659 Cumulative token usage for the dream across every pipeline stage.

887 The tokens that a dream has used so far.

888

889 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

890

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

660892

661893 - `cache_creation_input_tokens: number`

662894

663 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

895 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

664896

665897 format: int32

666898

667899 - `cache_read_input_tokens: number`

668900

669 Total tokens read from prompt cache.

901 The dream's input tokens that were read from the prompt cache.

670902

671903 format: int32

672904

673905 - `input_tokens: number`

674906

675 Total uncached input tokens consumed across every pipeline stage.

907 The dream's input tokens that weren't read from or written to the prompt cache.

676908

677909 format: int32

678910

679911 - `output_tokens: number`

680912

681 Total output tokens generated across every pipeline stage.

913 The tokens that the model generated for the dream.

682914

683915 format: int32

684916

685917- `next_page: string or null`

918

919 The cursor for the next page, or `null` if this is the last page.

920

921 Pass it as `page` to get the next page.

686922

687923### Example

688924

from line 982

746982

747983**GET** `/v1/dreams/{dream_id}`

748984

749Get a Dream

985Get a dream by ID to check its status, output memory store, and token usage.

986

987Archived dreams are returned too.

988

989See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#track-progress) for how to poll a dream and what each status means.

750990

751991### Path parameters

752992

753993- `dream_id: string`

754994

995 The ID of the dream to get (`drm_...`).

996

755997### Headers

756998

757999- `"anthropic-beta": optional array of AnthropicBeta`

from line 1098

8561098

8571099- `"anthropic-workspace-id": optional string`

8581100

1101 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

1102

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

1104

8591105### Returns

8601106

8611107- `BetaDream object`

8621108

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

1109 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.

1110

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

1112

1113 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.

8641114

8651115 - `type: "dream"`

8661116

8671117 - `id: string`

8681118

1119 The unique ID of the dream (`drm_...`).

1120

8691121 - `archived_at: string or null`

8701122

8711123 A timestamp in RFC 3339 format

from line 1142

8901142

8911143 - `type: string`

8921144

1145 A code for why the dream failed, such as `timeout` or `internal_error`.

1146

1147 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

1148

8931149 - `message: string`

8941150

1151 A human-readable explanation of why the dream failed.

1152

8951153 - `inputs: array of BetaDreamInput`

8961154

1155 The sources that the dream reads, from the request that created it.

1156

8971157 - `BetaDreamMemoryStoreInput object`

8981158

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

1159 The memory store that a dream reads, given as an entry in `inputs`.

1160

1161 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

9001162

9011163 - `type: "memory_store"`

9021164

9031165 - `memory_store_id: string`

9041166

1167 The ID of the memory store for the dream to read (`memstore_...`).

1168

1169 The memory store must be in the same workspace as the dream and must not be archived.

1170

9051171 minLength: 1

9061172

9071173 - `BetaDreamSessionsInput object`

9081174

909 Input session transcripts the dream reads.

1175 The sessions that a dream reads, given as an entry in `inputs`.

9101176

9111177 - `type: "sessions"`

9121178

9131179 - `session_ids: array of string`

9141180

1181 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

1182

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

1184

1185 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

1186

9151187 - `instructions: string or null`

9161188

1189 The guidance given when the dream was created, or `null` if none was given.

1190

9171191 - `model: BetaDreamModelConfig`

9181192

919 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

1193 The model that runs a dream, from the request that created it.

1194

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

9201196

9211197 - `id: string`

9221198

923 Model identifier, e.g. "claude-opus-5". 1-256 characters.

1199 The ID of the model that runs the dream, as given in the request that created it.

9241200

9251201 minLength: 1, maxLength: 256

9261202

from line 1210

9341210

9351211 - `output_behavior: BetaOutputBehavior`

9361212

1213 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

1214

9371215 - `BetaOutputBehaviorCreateNew object`

9381216

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

1217 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

1218

1219 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

9401220

9411221 - `type: "create_new"`

9421222

9431223 - `BetaOutputBehaviorUpdateExisting object`

9441224

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

1225 Write the result into the input memory store instead of a new memory store.

1226

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

9461228

9471229 - `type: "update_existing"`

9481230

9491231 - `memory_store_id: string`

9501232

1233 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`.

1234

9511235 minLength: 1

9521236

9531237 - `outputs: array of BetaDreamOutput`

9541238

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

1240

1241 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`.

1242

1243 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

1244

9551245 - `type: "memory_store"`

9561246

9571247 - `memory_store_id: string`

9581248

1249 The ID of the memory store that the dream writes its result to (`memstore_...`).

1250

1251 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

1252

9591253 - `session_id: string or null`

9601254

1255 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

1256

1257 Stream that session's events to follow what the dream reads and writes.

1258

1259 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

1260

9611261 - `status: BetaDreamStatus`

9621262

963 Lifecycle status of a Dream.

1263 Where a dream is in its lifecycle.

1264

1265 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

1266

1267 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

9641268

9651269 - `"pending"`

9661270

1271 The dream is waiting to start and hasn't read its inputs yet.

1272

1273 `outputs` is empty and every `usage` count is zero.

1274

9671275 - `"running"`

9681276

1277 The dream is reading its inputs and writing its result.

1278

1279 `usage` updates while the dream has this status.

1280

9691281 - `"completed"`

9701282

1283 The dream finished and its output memory store holds the complete result.

1284

9711285 - `"failed"`

9721286

1287 The dream stopped with an error, which `error` describes.

1288

1289 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

1290

9731291 - `"canceled"`

9741292

1293 A cancel request stopped the dream before it reached `completed` or `failed`.

1294

1295 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

1296

9751297 - `usage: BetaDreamUsage`

9761298

977 Cumulative token usage for the dream across every pipeline stage.

1299 The tokens that a dream has used so far.

1300

1301 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

1302

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

9781304

9791305 - `cache_creation_input_tokens: number`

9801306

981 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

1307 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

9821308

9831309 format: int32

9841310

9851311 - `cache_read_input_tokens: number`

9861312

987 Total tokens read from prompt cache.

1313 The dream's input tokens that were read from the prompt cache.

9881314

9891315 format: int32

9901316

9911317 - `input_tokens: number`

9921318

993 Total uncached input tokens consumed across every pipeline stage.

1319 The dream's input tokens that weren't read from or written to the prompt cache.

9941320

9951321 format: int32

9961322

9971323 - `output_tokens: number`

9981324

999 Total output tokens generated across every pipeline stage.

1325 The tokens that the model generated for the dream.

10001326

10011327 format: int32

10021328

from line 1383

10571383

10581384**POST** `/v1/dreams/{dream_id}/cancel`

10591385

1060Cancel a Dream

1386Stop a `pending` or `running` dream.

1387

1388The response shows `status` as `canceled`, unless the dream reached `completed` or `failed` first. `usage` can keep changing after the response. Canceling a `canceled` dream returns it unchanged. Canceling a `completed` or `failed` dream returns a 400 error.

1389

1390See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#cancel-a-dream) to learn more about canceling dreams.

10611391

10621392### Path parameters

10631393

10641394- `dream_id: string`

10651395

1396 The ID of the dream to cancel (`drm_...`).

1397

10661398### Headers

10671399

10681400- `"anthropic-beta": optional array of AnthropicBeta`

from line 1499

11671499

11681500- `"anthropic-workspace-id": optional string`

11691501

1502 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

1503

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

1505

11701506### Returns

11711507

11721508- `BetaDream object`

11731509

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

1510 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.

1511

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

1513

1514 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.

11751515

11761516 - `type: "dream"`

11771517

11781518 - `id: string`

11791519

1520 The unique ID of the dream (`drm_...`).

1521

11801522 - `archived_at: string or null`

11811523

11821524 A timestamp in RFC 3339 format

from line 1543

12011543

12021544 - `type: string`

12031545

1546 A code for why the dream failed, such as `timeout` or `internal_error`.

1547

1548 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

1549

12041550 - `message: string`

12051551

1552 A human-readable explanation of why the dream failed.

1553

12061554 - `inputs: array of BetaDreamInput`

12071555

1556 The sources that the dream reads, from the request that created it.

1557

12081558 - `BetaDreamMemoryStoreInput object`

12091559

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

1560 The memory store that a dream reads, given as an entry in `inputs`.

1561

1562 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

12111563

12121564 - `type: "memory_store"`

12131565

12141566 - `memory_store_id: string`

12151567

1568 The ID of the memory store for the dream to read (`memstore_...`).

1569

1570 The memory store must be in the same workspace as the dream and must not be archived.

1571

12161572 minLength: 1

12171573

12181574 - `BetaDreamSessionsInput object`

12191575

1220 Input session transcripts the dream reads.

1576 The sessions that a dream reads, given as an entry in `inputs`.

12211577

12221578 - `type: "sessions"`

12231579

12241580 - `session_ids: array of string`

12251581

1582 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

1583

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

1585

1586 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

1587

12261588 - `instructions: string or null`

12271589

1590 The guidance given when the dream was created, or `null` if none was given.

1591

12281592 - `model: BetaDreamModelConfig`

12291593

1230 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

1594 The model that runs a dream, from the request that created it.

1595

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

12311597

12321598 - `id: string`

12331599

1234 Model identifier, e.g. "claude-opus-5". 1-256 characters.

1600 The ID of the model that runs the dream, as given in the request that created it.

12351601

12361602 minLength: 1, maxLength: 256

12371603

from line 1611

12451611

12461612 - `output_behavior: BetaOutputBehavior`

12471613

1614 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

1615

12481616 - `BetaOutputBehaviorCreateNew object`

12491617

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

1618 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

1619

1620 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

12511621

12521622 - `type: "create_new"`

12531623

12541624 - `BetaOutputBehaviorUpdateExisting object`

12551625

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

1626 Write the result into the input memory store instead of a new memory store.

1627

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

12571629

12581630 - `type: "update_existing"`

12591631

12601632 - `memory_store_id: string`

12611633

1634 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`.

1635

12621636 minLength: 1

12631637

12641638 - `outputs: array of BetaDreamOutput`

12651639

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

1641

1642 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`.

1643

1644 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

1645

12661646 - `type: "memory_store"`

12671647

12681648 - `memory_store_id: string`

12691649

1650 The ID of the memory store that the dream writes its result to (`memstore_...`).

1651

1652 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

1653

12701654 - `session_id: string or null`

12711655

1656 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

1657

1658 Stream that session's events to follow what the dream reads and writes.

1659

1660 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

1661

12721662 - `status: BetaDreamStatus`

12731663

1274 Lifecycle status of a Dream.

1664 Where a dream is in its lifecycle.

1665

1666 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

1667

1668 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

12751669

12761670 - `"pending"`

12771671

1672 The dream is waiting to start and hasn't read its inputs yet.

1673

1674 `outputs` is empty and every `usage` count is zero.

1675

12781676 - `"running"`

12791677

1678 The dream is reading its inputs and writing its result.

1679

1680 `usage` updates while the dream has this status.

1681

12801682 - `"completed"`

12811683

1684 The dream finished and its output memory store holds the complete result.

1685

12821686 - `"failed"`

12831687

1688 The dream stopped with an error, which `error` describes.

1689

1690 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

1691

12841692 - `"canceled"`

12851693

1694 A cancel request stopped the dream before it reached `completed` or `failed`.

1695

1696 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

1697

12861698 - `usage: BetaDreamUsage`

12871699

1288 Cumulative token usage for the dream across every pipeline stage.

1700 The tokens that a dream has used so far.

1701

1702 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

1703

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

12891705

12901706 - `cache_creation_input_tokens: number`

12911707

1292 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

1708 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

12931709

12941710 format: int32

12951711

12961712 - `cache_read_input_tokens: number`

12971713

1298 Total tokens read from prompt cache.

1714 The dream's input tokens that were read from the prompt cache.

12991715

13001716 format: int32

13011717

13021718 - `input_tokens: number`

13031719

1304 Total uncached input tokens consumed across every pipeline stage.

1720 The dream's input tokens that weren't read from or written to the prompt cache.

13051721

13061722 format: int32

13071723

13081724 - `output_tokens: number`

13091725

1310 Total output tokens generated across every pipeline stage.

1726 The tokens that the model generated for the dream.

13111727

13121728 format: int32

13131729

from line 1785

13691785

13701786**POST** `/v1/dreams/{dream_id}/archive`

13711787

1372Archive a Dream

1788Hide a `completed`, `failed`, or `canceled` dream from the default list of dreams.

1789

1790Archiving a `pending` or `running` dream returns a 400 error, so cancel it first. Archiving an archived dream returns it unchanged. An archived dream can still be fetched by ID. Archiving can't be undone.

1791

1792See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#archive-a-dream) to learn more about archiving dreams.

13731793

13741794### Path parameters

13751795

13761796- `dream_id: string`

13771797

1798 The ID of the dream to archive (`drm_...`).

1799

13781800### Headers

13791801

13801802- `"anthropic-beta": optional array of AnthropicBeta`

from line 1901

14791901

14801902- `"anthropic-workspace-id": optional string`

14811903

1904 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

1905

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

1907

14821908### Returns

14831909

14841910- `BetaDream object`

14851911

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

1912 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.

1913

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

1915

1916 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.

14871917

14881918 - `type: "dream"`

14891919

14901920 - `id: string`

14911921

1922 The unique ID of the dream (`drm_...`).

1923

14921924 - `archived_at: string or null`

14931925

14941926 A timestamp in RFC 3339 format

from line 1945

15131945

15141946 - `type: string`

15151947

1948 A code for why the dream failed, such as `timeout` or `internal_error`.

1949

1950 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

1951

15161952 - `message: string`

15171953

1954 A human-readable explanation of why the dream failed.

1955

15181956 - `inputs: array of BetaDreamInput`

15191957

1958 The sources that the dream reads, from the request that created it.

1959

15201960 - `BetaDreamMemoryStoreInput object`

15211961

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

1962 The memory store that a dream reads, given as an entry in `inputs`.

1963

1964 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

15231965

15241966 - `type: "memory_store"`

15251967

15261968 - `memory_store_id: string`

15271969

1970 The ID of the memory store for the dream to read (`memstore_...`).

1971

1972 The memory store must be in the same workspace as the dream and must not be archived.

1973

15281974 minLength: 1

15291975

15301976 - `BetaDreamSessionsInput object`

15311977

1532 Input session transcripts the dream reads.

1978 The sessions that a dream reads, given as an entry in `inputs`.

15331979

15341980 - `type: "sessions"`

15351981

15361982 - `session_ids: array of string`

15371983

1984 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

1985

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

1987

1988 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

1989

15381990 - `instructions: string or null`

15391991

1992 The guidance given when the dream was created, or `null` if none was given.

1993

15401994 - `model: BetaDreamModelConfig`

15411995

1542 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

1996 The model that runs a dream, from the request that created it.

1997

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

15431999

15442000 - `id: string`

15452001

1546 Model identifier, e.g. "claude-opus-5". 1-256 characters.

2002 The ID of the model that runs the dream, as given in the request that created it.

15472003

15482004 minLength: 1, maxLength: 256

15492005

from line 2013

15572013

15582014 - `output_behavior: BetaOutputBehavior`

15592015

2016 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

2017

15602018 - `BetaOutputBehaviorCreateNew object`

15612019

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

2020 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

2021

2022 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

15632023

15642024 - `type: "create_new"`

15652025

15662026 - `BetaOutputBehaviorUpdateExisting object`

15672027

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

2028 Write the result into the input memory store instead of a new memory store.

2029

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

15692031

15702032 - `type: "update_existing"`

15712033

15722034 - `memory_store_id: string`

15732035

2036 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`.

2037

15742038 minLength: 1

15752039

15762040 - `outputs: array of BetaDreamOutput`

15772041

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

2043

2044 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`.

2045

2046 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

2047

15782048 - `type: "memory_store"`

15792049

15802050 - `memory_store_id: string`

15812051

2052 The ID of the memory store that the dream writes its result to (`memstore_...`).

2053

2054 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

2055

15822056 - `session_id: string or null`

15832057

2058 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

2059

2060 Stream that session's events to follow what the dream reads and writes.

2061

2062 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

2063

15842064 - `status: BetaDreamStatus`

15852065

1586 Lifecycle status of a Dream.

2066 Where a dream is in its lifecycle.

2067

2068 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

2069

2070 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

15872071

15882072 - `"pending"`

15892073

2074 The dream is waiting to start and hasn't read its inputs yet.

2075

2076 `outputs` is empty and every `usage` count is zero.

2077

15902078 - `"running"`

15912079

2080 The dream is reading its inputs and writing its result.

2081

2082 `usage` updates while the dream has this status.

2083

15922084 - `"completed"`

15932085

2086 The dream finished and its output memory store holds the complete result.

2087

15942088 - `"failed"`

15952089

2090 The dream stopped with an error, which `error` describes.

2091

2092 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

2093

15962094 - `"canceled"`

15972095

2096 A cancel request stopped the dream before it reached `completed` or `failed`.

2097

2098 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

2099

15982100 - `usage: BetaDreamUsage`

15992101

1600 Cumulative token usage for the dream across every pipeline stage.

2102 The tokens that a dream has used so far.

2103

2104 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

2105

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

16012107

16022108 - `cache_creation_input_tokens: number`

16032109

1604 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

2110 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

16052111

16062112 format: int32

16072113

16082114 - `cache_read_input_tokens: number`

16092115

1610 Total tokens read from prompt cache.

2116 The dream's input tokens that were read from the prompt cache.

16112117

16122118 format: int32

16132119

16142120 - `input_tokens: number`

16152121

1616 Total uncached input tokens consumed across every pipeline stage.

2122 The dream's input tokens that weren't read from or written to the prompt cache.

16172123

16182124 format: int32

16192125

16202126 - `output_tokens: number`

16212127

1622 Total output tokens generated across every pipeline stage.

2128 The tokens that the model generated for the dream.

16232129

16242130 format: int32

16252131

from line 2189

16832189

16842190- `BetaDream object`

16852191

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

2192 An asynchronous job that reads a memory store and past sessions, then writes a reorganized version of that memory store.

2193

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

2195

2196 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#how-it-works) for what a dream reads and produces.

16872197

16882198 - `type: "dream"`

16892199

16902200 - `id: string`

16912201

2202 The unique ID of the dream (`drm_...`).

2203

16922204 - `archived_at: string or null`

16932205

16942206 A timestamp in RFC 3339 format

from line 2225

17132225

17142226 - `type: string`

17152227

2228 A code for why the dream failed, such as `timeout` or `internal_error`.

2229

2230 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

2231

17162232 - `message: string`

17172233

2234 A human-readable explanation of why the dream failed.

2235

17182236 - `inputs: array of BetaDreamInput`

17192237

2238 The sources that the dream reads, from the request that created it.

2239

17202240 - `BetaDreamMemoryStoreInput object`

17212241

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

2242 The memory store that a dream reads, given as an entry in `inputs`.

2243

2244 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

17232245

17242246 - `type: "memory_store"`

17252247

17262248 - `memory_store_id: string`

17272249

2250 The ID of the memory store for the dream to read (`memstore_...`).

2251

2252 The memory store must be in the same workspace as the dream and must not be archived.

2253

17282254 minLength: 1

17292255

17302256 - `BetaDreamSessionsInput object`

17312257

1732 Input session transcripts the dream reads.

2258 The sessions that a dream reads, given as an entry in `inputs`.

17332259

17342260 - `type: "sessions"`

17352261

17362262 - `session_ids: array of string`

17372263

2264 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

2265

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

2267

2268 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

2269

17382270 - `instructions: string or null`

17392271

2272 The guidance given when the dream was created, or `null` if none was given.

2273

17402274 - `model: BetaDreamModelConfig`

17412275

1742 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

2276 The model that runs a dream, from the request that created it.

2277

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

17432279

17442280 - `id: string`

17452281

1746 Model identifier, e.g. "claude-opus-5". 1-256 characters.

2282 The ID of the model that runs the dream, as given in the request that created it.

17472283

17482284 minLength: 1, maxLength: 256

17492285

from line 2293

17572293

17582294 - `output_behavior: BetaOutputBehavior`

17592295

2296 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

2297

17602298 - `BetaOutputBehaviorCreateNew object`

17612299

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

2300 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

2301

2302 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

17632303

17642304 - `type: "create_new"`

17652305

17662306 - `BetaOutputBehaviorUpdateExisting object`

17672307

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

2308 Write the result into the input memory store instead of a new memory store.

2309

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

17692311

17702312 - `type: "update_existing"`

17712313

17722314 - `memory_store_id: string`

17732315

2316 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`.

2317

17742318 minLength: 1

17752319

17762320 - `outputs: array of BetaDreamOutput`

17772321

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

2323

2324 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`.

2325

2326 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#use-the-output) for how to review and use the result.

2327

17782328 - `type: "memory_store"`

17792329

17802330 - `memory_store_id: string`

17812331

2332 The ID of the memory store that the dream writes its result to (`memstore_...`).

2333

2334 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

2335

17822336 - `session_id: string or null`

17832337

2338 The ID of the session that runs the dream (`sesn_...`), or `null` if that session hasn't started.

2339

2340 Stream that session's events to follow what the dream reads and writes.

2341

2342 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#watch-the-pipeline-run) for how to watch a running dream.

2343

17842344 - `status: BetaDreamStatus`

17852345

1786 Lifecycle status of a Dream.

2346 Where a dream is in its lifecycle.

2347

2348 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

2349

2350 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

17872351

17882352 - `"pending"`

17892353

2354 The dream is waiting to start and hasn't read its inputs yet.

2355

2356 `outputs` is empty and every `usage` count is zero.

2357

17902358 - `"running"`

17912359

2360 The dream is reading its inputs and writing its result.

2361

2362 `usage` updates while the dream has this status.

2363

17922364 - `"completed"`

17932365

2366 The dream finished and its output memory store holds the complete result.

2367

17942368 - `"failed"`

17952369

2370 The dream stopped with an error, which `error` describes.

2371

2372 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

2373

17962374 - `"canceled"`

17972375

2376 A cancel request stopped the dream before it reached `completed` or `failed`.

2377

2378 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

2379

17982380 - `usage: BetaDreamUsage`

17992381

1800 Cumulative token usage for the dream across every pipeline stage.

2382 The tokens that a dream has used so far.

2383

2384 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

2385

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

18012387

18022388 - `cache_creation_input_tokens: number`

18032389

1804 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

2390 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

18052391

18062392 format: int32

18072393

18082394 - `cache_read_input_tokens: number`

18092395

1810 Total tokens read from prompt cache.

2396 The dream's input tokens that were read from the prompt cache.

18112397

18122398 format: int32

18132399

18142400 - `input_tokens: number`

18152401

1816 Total uncached input tokens consumed across every pipeline stage.

2402 The dream's input tokens that weren't read from or written to the prompt cache.

18172403

18182404 format: int32

18192405

18202406 - `output_tokens: number`

18212407

1822 Total output tokens generated across every pipeline stage.

2408 The tokens that the model generated for the dream.

18232409

18242410 format: int32

18252411

from line 2417

18312417

18322418 - `type: string`

18332419

2420 A code for why the dream failed, such as `timeout` or `internal_error`.

2421

2422 The [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#errors) lists common error codes and when they occur.

2423

18342424 - `message: string`

18352425

2426 A human-readable explanation of why the dream failed.

2427

18362428### Beta Dream Input

18372429

18382430- `BetaDreamInput = BetaDreamMemoryStoreInput or BetaDreamSessionsInput`

18392431

2432 A source that a dream reads, such as a memory store or a set of sessions.

2433

18402434 - `BetaDreamMemoryStoreInput object`

18412435

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

2436 The memory store that a dream reads, given as an entry in `inputs`.

2437

2438 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

18432439

18442440 - `type: "memory_store"`

18452441

18462442 - `memory_store_id: string`

18472443

2444 The ID of the memory store for the dream to read (`memstore_...`).

2445

2446 The memory store must be in the same workspace as the dream and must not be archived.

2447

18482448 minLength: 1

18492449

18502450 - `BetaDreamSessionsInput object`

18512451

1852 Input session transcripts the dream reads.

2452 The sessions that a dream reads, given as an entry in `inputs`.

18532453

18542454 - `type: "sessions"`

18552455

18562456 - `session_ids: array of string`

18572457

2458 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

2459

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

2461

2462 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

2463

18582464### Beta Dream Memory Store Input

18592465

18602466- `BetaDreamMemoryStoreInput object`

18612467

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

2468 The memory store that a dream reads, given as an entry in `inputs`.

2469

2470 With `output_behavior` set to `update_existing`, the dream writes its result into this memory store. Otherwise the dream doesn't change it.

18632471

18642472 - `type: "memory_store"`

18652473

18662474 - `memory_store_id: string`

18672475

2476 The ID of the memory store for the dream to read (`memstore_...`).

2477

2478 The memory store must be in the same workspace as the dream and must not be archived.

2479

18682480 minLength: 1

18692481

18702482### Beta Dream Memory Store Output

18712483

18722484- `BetaDreamMemoryStoreOutput object`

18732485

1874 An output memory store the dream writes consolidated memories into.

2486 The memory store that holds a dream's result, as an entry in `outputs`.

18752487

18762488 - `type: "memory_store"`

18772489

18782490 - `memory_store_id: string`

18792491

2492 The ID of the memory store that the dream writes its result to (`memstore_...`).

2493

2494 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

2495

18802496### Beta Dream Model Config

18812497

18822498- `BetaDreamModelConfig object`

18832499

1884 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.

2500 The model that runs a dream, from the request that created it.

2501

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

18852503

18862504 - `id: string`

18872505

1888 Model identifier, e.g. "claude-opus-5". 1-256 characters.

2506 The ID of the model that runs the dream, as given in the request that created it.

18892507

18902508 minLength: 1, maxLength: 256

18912509

from line 2519

19012519

19022520- `BetaDreamModelConfigParam object`

19032521

1904 Model identifier and configuration applied to every pipeline stage.

2522 The object form of `model` in a request to create a dream.

19052523

19062524 - `id: string`

19072525

1908 Model identifier, e.g. "claude-opus-5". 1-256 characters.

2526 The ID of the model to run the dream with.

2527

2528 The ID can be 1 to 256 characters long.

2529

2530 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists the supported models.

19092531

19102532 minLength: 1, maxLength: 256

19112533

from line 2543

19212543

19222544- `BetaDreamOutput object`

19232545

1924 An output memory store the dream writes consolidated memories into.

2546 The memory store that holds a dream's result, as an entry in `outputs`.

19252547

19262548 - `type: "memory_store"`

19272549

19282550 - `memory_store_id: string`

19292551

2552 The ID of the memory store that the dream writes its result to (`memstore_...`).

2553

2554 With `output_behavior` set to `create_new`, this is a new memory store. With `update_existing`, it is the input memory store.

2555

19302556### Beta Dream Sessions Input

19312557

19322558- `BetaDreamSessionsInput object`

19332559

1934 Input session transcripts the dream reads.

2560 The sessions that a dream reads, given as an entry in `inputs`.

19352561

19362562 - `type: "sessions"`

19372563

19382564 - `session_ids: array of string`

19392565

2566 The IDs of the sessions whose transcripts the dream reads (`sesn_...`).

2567

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

2569

2570 The [limits table in the Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#limits) lists all the limits on a dream.

2571

19402572### Beta Dream Status

19412573

19422574- `BetaDreamStatus = "pending" or "running" or "completed" or 2 more`

19432575

1944 Lifecycle status of a Dream.

2576 Where a dream is in its lifecycle.

2577

2578 `completed`, `failed`, and `canceled` are final: once a dream has one of these statuses, its status doesn't change again.

2579

2580 See the [Dreams guide](https://platform.claude.com/docs/en/managed-agents/dreams#lifecycle) for what each status means.

19452581

19462582 - `"pending"`

19472583

2584 The dream is waiting to start and hasn't read its inputs yet.

2585

2586 `outputs` is empty and every `usage` count is zero.

2587

19482588 - `"running"`

19492589

2590 The dream is reading its inputs and writing its result.

2591

2592 `usage` updates while the dream has this status.

2593

19502594 - `"completed"`

19512595

2596 The dream finished and its output memory store holds the complete result.

2597

19522598 - `"failed"`

19532599

2600 The dream stopped with an error, which `error` describes.

2601

2602 If `outputs` references a memory store, that memory store keeps what the dream wrote before it stopped.

2603

19542604 - `"canceled"`

19552605

2606 A cancel request stopped the dream before it reached `completed` or `failed`.

2607

2608 If `outputs` references a memory store, that memory store keeps what the dream wrote. `usage` can keep changing after the cancel.

2609

19562610### Beta Dream Usage

19572611

19582612- `BetaDreamUsage object`

19592613

1960 Cumulative token usage for the dream across every pipeline stage.

2614 The tokens that a dream has used so far.

2615

2616 The counts are zero while the dream is `pending` and update while it is `running`. They can keep changing after a cancel.

2617

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

19612619

19622620 - `cache_creation_input_tokens: number`

19632621

1964 Total tokens used to create prompt-cache entries (sum of all TTL tiers).

2622 The dream's input tokens that were written to the prompt cache, for both the 5-minute and 1-hour cache durations.

19652623

19662624 format: int32

19672625

19682626 - `cache_read_input_tokens: number`

19692627

1970 Total tokens read from prompt cache.

2628 The dream's input tokens that were read from the prompt cache.

19712629

19722630 format: int32

19732631

19742632 - `input_tokens: number`

19752633

1976 Total uncached input tokens consumed across every pipeline stage.

2634 The dream's input tokens that weren't read from or written to the prompt cache.

19772635

19782636 format: int32

19792637

19802638 - `output_tokens: number`

19812639

1982 Total output tokens generated across every pipeline stage.

2640 The tokens that the model generated for the dream.

19832641

19842642 format: int32

19852643

from line 2737

20792737

20802738 - `BetaTargetStoreHeldError object`

20812739

2082 The `output_behavior.memory_store_id` target is still held by a prior `{type: "update_existing"}` dream — one that is `pending` or `running`, or was canceled with its final writes still landing. Rarely the named dream has just finished (`completed`/`failed`) and its execution is still closing; an immediate retry then almost always succeeds. The message names the holding dream when the server can identify it (rarely omitted); poll it to a terminal state or cancel it, then retry. Carried with `x-should-retry: false`.

2740 Returned with status 409 when a request to create a dream sets `output_behavior` to `update_existing` and another dream that writes into the same memory store hasn't fully stopped.

2741

2742 The other dream is `pending` or `running`, or it has just stopped and is still finishing its last writes. `message` gives the ID of the other dream when the server can identify it. If that dream has already reached `completed`, `failed`, or `canceled`, retry after a short wait. Otherwise, wait for the other dream to end or cancel it, then retry. The response sets the `x-should-retry` header to `false`.

20832743

20842744 - `type: "conflict_error"`

20852745

20862746 - `message: optional string`

20872747

2088 Human-readable description of the conflict, naming the dream that holds the target store when the server can identify it.

2748 A human-readable explanation of why the memory store can't be used yet, with the ID of the dream that is using it when the server can identify it.

20892749

20902750### Beta Output Behavior

20912751

20922752- `BetaOutputBehavior = BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting`

20932753

2754 Which memory store a dream writes its result to. Defaults to `create_new` when left out of a create request.

2755

20942756 - `BetaOutputBehaviorCreateNew object`

20952757

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

2758 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

2759

2760 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

20972761

20982762 - `type: "create_new"`

20992763

21002764 - `BetaOutputBehaviorUpdateExisting object`

21012765

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

2766 Write the result into the input memory store instead of a new memory store.

2767

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

21032769

21042770 - `type: "update_existing"`

21052771

21062772 - `memory_store_id: string`

21072773

2774 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`.

2775

21082776 minLength: 1

21092777

21102778### Beta Output Behavior Create New

21112779

21122780- `BetaOutputBehaviorCreateNew object`

21132781

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

2782 Write the result to a new memory store that starts as a copy of the input memory store. This is the default.

2783

2784 The new memory store is in the same workspace as the dream. The dream doesn't change the input memory store.

21152785

21162786 - `type: "create_new"`

21172787

from line 2789

21192789

21202790- `BetaOutputBehaviorUpdateExisting object`

21212791

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

2792 Write the result into the input memory store instead of a new memory store.

2793

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

21232795

21242796 - `type: "update_existing"`

21252797

21262798 - `memory_store_id: string`

21272799

2800 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`.

2801

21282802 minLength: 1

21292803

21302804### Beta Target Store Held Error

21312805

21322806- `BetaTargetStoreHeldError object`

21332807

2134 The `output_behavior.memory_store_id` target is still held by a prior `{type: "update_existing"}` dream — one that is `pending` or `running`, or was canceled with its final writes still landing. Rarely the named dream has just finished (`completed`/`failed`) and its execution is still closing; an immediate retry then almost always succeeds. The message names the holding dream when the server can identify it (rarely omitted); poll it to a terminal state or cancel it, then retry. Carried with `x-should-retry: false`.

2808 Returned with status 409 when a request to create a dream sets `output_behavior` to `update_existing` and another dream that writes into the same memory store hasn't fully stopped.

2809

2810 The other dream is `pending` or `running`, or it has just stopped and is still finishing its last writes. `message` gives the ID of the other dream when the server can identify it. If that dream has already reached `completed`, `failed`, or `canceled`, retry after a short wait. Otherwise, wait for the other dream to end or cancel it, then retry. The response sets the `x-should-retry` header to `false`.

21352811

21362812 - `type: "conflict_error"`

21372813

21382814 - `message: optional string`

21392815

2140 Human-readable description of the conflict, naming the dream that holds the target store when the server can identify it.

2816 A human-readable explanation of why the memory store can't be used yet, with the ID of the dream that is using it when the server can identify it.

21412817

This page’s history 9 edits

21 Sep 2026 +794 −118 · this one
16 Sep 2026 +15 −5
11 Sep 2026 +361 −383
10 Sep 2026 +588 −563
1 Sep 2026 +153 −5
26 Aug 2026 +75 −5

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

Dreams changed

The whole hunk