Trigger an asynchronous memory consolidation task.
POST /api/v1/forward/dreams
A Dream can consolidate a Memory Store directly or the Default Memory of a specified Identity and Template. The task runs in the background after the API returns. Use the get or list endpoint to check its status.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or admin SAT>. |
Content-Type | Yes | Must be application/json. |
Request body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
inputs | object[] | Yes | — | Input list. Must contain exactly one primary input of type memory_store or identity_template. Additional sessions inputs are allowed. |
model | string | object | null | No | auto | Model ID or a Dream model object that can specify reasoning effort and context window. Omitted, null, or empty-string values use auto. |
instructions | string | No | "" | Custom consolidation instructions, at most 4096 bytes when UTF-8 encoded (multibyte characters occupy multiple bytes). |
inputs elements
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Input type: memory_store, identity_template, or sessions. |
memory_store_id | string | Conditional | Required when type=memory_store. Specifies a Memory Store accessible to the caller. |
identity_id | string | Conditional | Required when type=identity_template. |
template_id | string | Conditional | Required when type=identity_template. |
session_ids | string[] | Conditional | Required and non-empty when type=sessions. All sessions inputs combined can contain at most 100 Session IDs. |
identity_template input cannot also contain memory_store_id.
See Dream input for how the two primary input types are processed.
model object
Existing string requests remain supported, for example "model": "auto". You can also pass an object:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Nonempty model ID. Use an available, enabled ID returned by List Models. |
effort | string | No | Reasoning effort: none, low, medium, high, xhigh, or max. Values other than none must be in the selected model's efforts; none explicitly disables reasoning. |
context_window | integer | No | Context window in tokens; must be a positive integer. If the model has a nonempty available_context_windows list, select a value from it; no tier restriction applies when the catalog declares no tiers. |
- The two options can be omitted independently. Invalid values such as explicit null, empty effort, or a zero or negative window return 400.
- Omitting the entire
model, or passing null or a blank string, usesauto. An object must contain a nonemptyid;{}is not equivalent to auto. - When
autohas options, the model catalog must contain an available entry that supports those options. The object supports only the three fields above; unknown fields return 400, witherror.parampointing to the corresponding field. - The example only illustrates the format. Query the models and parameters available to the current identity before use.
Example request
Consolidate the Default Memory of an Identity and Template:
Example response
HTTP 201 Created
Response fields
| Field | Type | Description |
|---|---|---|
| Return value | object | The newly created Dream object. |
Errors
| HTTP | Type | Trigger |
|---|---|---|
400 | invalid_request_error | Invalid request body or input combination, unavailable model, invalid model options, or unknown fields. error.code can be invalid_dream_inputs, too_many_sessions, invalid_model, or instructions_too_long. |
401 | authentication_error | Authentication is missing, invalid, or expired. |
403 | permission_error | The token cannot manage Dreams. Identity SAT is not supported by this endpoint. |
404 | not_found_error | The Memory Store does not exist or is inaccessible, or the specified Identity, Template, or Default Memory does not exist. error.code is memory_store_not_found or dream_scope_not_found. |
409 | invalid_request_error | The current personal space or Workspace already has a Dream in the pending or running state. |
413 | invalid_request_error | The request body exceeds the size limit. |
429 | rate_limit_error | The request rate or concurrency limit has been reached. |
500/502/503 | api_error | The service or an internal dependency is temporarily unavailable. |