Skip to main content
Sessions

更新 Session

更新 Forward Session 的标题、metadata、环境变量或模型配置。

POST /api/v1/forward/sessions/{session_id} config 支持更新 environment_variables 和 model。模型更新仅作用于本 Session，不修改 Template 或 Identity Config。

请求头

Header是否必填说明
Authorization是Bearer <PAT 或 SAT>
Content-Type是application/json
Idempotency-Key否有副作用请求可选的幂等键。

路径参数

参数类型是否必填说明
session_idstring是Session ID。

请求体参数

参数类型是否必填说明
titlestring否新的 Session 标题。
metadataobject否metadata merge patch；传入的 key 覆盖已有 key，未出现的 key 保留。
configobject否Session 配置更新，只允许包含 environment_variables 和 model。null 不合法；省略或 {} 不修改现有配置。
config.environment_variablesobject<string, string>（推荐）否Session 环境变量；新接入请将每个 value 都作为字符串传入。传入的 map 整组替换已有的 Session 级环境变量，替换后在 Template + Identity Config 编译结果基础上追加合并，同名变量覆盖基础层的值。
config.modelstring | object | null否非 null 值整值替换 Session 模型覆盖；null 删除覆盖并恢复继承；省略保持当前模型覆盖。
config.environment_variables 更新语义：
  • 缺省或 config 为 {}：不修改环境变量。
  • 非空 object：整组替换 Session 级环境变量 map，不与旧值增量合并，未出现的旧 key 会被删除。
  • 空 object {}：清空 Session 级环境变量。
  • value 请使用字符串；object、array value 不合法。
  • 整组替换只作用于 Session 级这一层；更新后 Session 的运行时环境变量仍在 Template + Identity Config 编译结果基础上追加合并，同名变量以 Session 级的值覆盖。
  • 环境变量名称、保留字与容量限制由运行时校验，不合法时返回 400。

config.model

config.model 支持非空模型 ID 字符串（例如 "ultimate"），或包含模型 ID 和可选调优参数的对象，与 Template / Identity Config 的模型格式一致。可用模型和支持的选项请查询列出模型。
对象字段类型是否必填说明
idstring是非空模型 ID，取自列出模型返回的 id。
effortstring否Reasoning effort 等级：none、low、medium、high、xhigh、max；实际支持的等级以模型的 efforts 为准，省略时使用模型默认值。
speedstring否推理速度：standard、high；省略时使用 standard。实际支持的速度以模型的 speed 数组为准。
context_windowinteger否上下文窗口的 token 数，必须为正整数；请从模型的 available_context_windows 中选择，省略时使用模型默认窗口。
模型与选项组合是否可用，以列出模型的能力和运行时校验结果为准。
  • 省略 config.model：保持当前配置。
  • 传入 string / object：整体替换模型配置，未提交的旧选项不保留，新配置用于后续模型调用。
  • 传入 null：删除 Session 模型覆盖，恢复继承当前 Template / Identity Config 的模型。
  • 传入 {}：返回 400；模型对象必须包含非空 id。
template.model 是模板摘要；Session 模型覆盖值请查看响应中的 config.model。

示例请求

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated session title",
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  }
}'

示例响应

HTTP 200 OK 
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Updated session title",
  "metadata": {
    "source": "mobile",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "total_credits": 12.7
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T12:00:00Z"
}

响应字段

字段类型说明
返回值object更新后的 Session 对象。
config.modelstring | object更新后保存的 Session 模型覆盖值，保留 string / object 形态；删除覆盖后省略。

错误

HTTPTypeCode触发条件
503api_errorsession_materialization_busy更新 config.environment_variables 或 config.model 时需要刷新会话配置，但运行时返回版本或状态冲突。响应包含 Retry-After: 1；等待当前 Turn 完成后重试。
400invalid_request_errorinvalid_request更新请求体不合法，包括 config.model 为 {}、空 ID、非法类型或参数，以及不支持的配置字段。
400invalid_request_errorinvalid_request_body请求体 JSON 不合法，或 config、config.environment_variables 不合法。
404not_found_errorsession_not_foundSession 不存在。
409invalid_request_errorsession_archivedSession 已归档。
401authentication_error-PAT 或 SAT 无效或已过期。

备注

  • 仅更新标题或 metadata 不触发上述配置刷新。环境变量或模型更新收到 session_materialization_busy 时，遵循 Retry-After 并等待当前 Turn 完成，再用相同请求体重试；原请求携带 Idempotency-Key 时沿用同一键。该临时拒绝不会被缓存为最终幂等响应；此规则仅适用于该错误码。
  • resources 是创建时配置，不能通过本接口修改；如需在会话进行中追加文件资源，请使用添加 Session 资源接口。
  • 响应中的 config.environment_variables 反映更新后的结果。
  • 仅为兼容既有调用，非字符串标量 value 会规范化为字符串（null 为空字符串）；新接入请使用字符串 value。

相关

获取 Session

归档 Session

添加 Session 资源