Create a Dream

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	No	`auto`	Model tier: `auto`, `lite`, or `ultimate`.
`instructions`	string	No	`""`	Custom consolidation instructions, up to 4096 characters.

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

Each input can contain only the fields defined for its type. For example, an identity_template input cannot also contain memory_store_id. See Dream input for how the two primary input types are processed.

Example request

Consolidate the Default Memory of an Identity and Template:

curl -s -X POST 'https://api.qoder.com/api/v1/forward/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": [
      {
        "type": "identity_template",
        "identity_id": "idn_019eabc123",
        "template_id": "tmpl_support"
      },
      {
        "type": "sessions",
        "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"]
      }
    ],
    "model": "auto",
    "instructions": "Focus on long-term preferences confirmed by the user"
  }'

Consolidate a Memory Store directly:

curl -s -X POST 'https://api.qoder.com/api/v1/forward/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": [
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4"
      }
    ]
  }'

Example response

HTTP 201 Created

{
  "id": "drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9",
  "type": "dream",
  "status": "pending",
  "inputs": [
    {
      "type": "identity_template",
      "identity_id": "idn_019eabc123",
      "template_id": "tmpl_support"
    },
    {
      "type": "sessions",
      "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"]
    }
  ],
  "outputs": [],
  "model": { "id": "auto" },
  "instructions": "Focus on long-term preferences confirmed by the user",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "error": null,
  "created_at": "2026-09-15T03:00:00Z",
  "ended_at": null,
  "archived_at": null
}

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

Create a Dream

Headers

Request body

`inputs` elements

Example request

Example response

Response fields

Errors

Get a Dream

List Dreams

​Headers

​Request body

​inputs elements

​Example request

​Example response

​Response fields

​Errors

​Related

Get a Dream

List Dreams

Headers

Request body

`inputs` elements

Example request

Example response

Response fields

Errors

Related