Skip to main content

Create a Dream

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

HeaderRequiredDescription
AuthorizationYesBearer <PAT or admin SAT>.
Content-TypeYesMust be application/json.

Request body

FieldTypeRequiredDefaultDescription
inputsobject[]Yes—Input list. Must contain exactly one primary input of type memory_store or identity_template. Additional sessions inputs are allowed.
modelstring | object | nullNoautoModel ID or a Dream model object that can specify reasoning effort and context window. Omitted, null, or empty-string values use auto.
instructionsstringNo""Custom consolidation instructions, at most 4096 bytes when UTF-8 encoded (multibyte characters occupy multiple bytes).

inputs elements

FieldTypeRequiredDescription
typestringYesInput type: memory_store, identity_template, or sessions.
memory_store_idstringConditionalRequired when type=memory_store. Specifies a Memory Store accessible to the caller.
identity_idstringConditionalRequired when type=identity_template.
template_idstringConditionalRequired when type=identity_template.
session_idsstring[]ConditionalRequired 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.

model object

Existing string requests remain supported, for example "model": "auto". You can also pass an object:
{"model":{"id":"dfmodel","effort":"high","context_window":400000}}
FieldTypeRequiredDescription
idstringYesNonempty model ID. Use an available, enabled ID returned by List Models.
effortstringNoReasoning 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_windowintegerNoContext 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, uses auto. An object must contain a nonempty id; {} is not equivalent to auto.
  • When auto has 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, with error.param pointing 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:
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

FieldTypeDescription
Return valueobjectThe newly created Dream object.

Errors

HTTPTypeTrigger
400invalid_request_errorInvalid 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.
401authentication_errorAuthentication is missing, invalid, or expired.
403permission_errorThe token cannot manage Dreams. Identity SAT is not supported by this endpoint.
404not_found_errorThe 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.
409invalid_request_errorThe current personal space or Workspace already has a Dream in the pending or running state.
413invalid_request_errorThe request body exceeds the size limit.
429rate_limit_errorThe request rate or concurrency limit has been reached.
500/502/503api_errorThe service or an internal dependency is temporarily unavailable.