POST /api/v1/forward/sessions
Forward 会先编译 Template 基线与 Identity Config 覆盖层，再创建运行时 Session。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 否 | 有副作用请求可选的幂等键。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| identity_id | string | 是 | Forward Identity ID。 |
| template_id | string | 是 | Forward Template ID。 |
| title | string | 否 | Session 标题。 |
| incremental_streaming_enabled | boolean | 否 | 是否开启 assistant 增量流式事件，默认 false。 |
| metadata | object | 否 | 业务元数据。 |
| config | object | 否 | 单次 Session 配置覆盖，只接受白名单字段。 |
| config.environment_variables | object | 否 | Session 环境变量 key-value。 |
| resources | array | 否 | Session 级资源，当前用于挂载文件。 |
| resources[].type | string | 条件必填 | 资源类型，当前为 file。 |
| resources[].file_id | string | 条件必填 | Files API 返回的 File ID。 |
| resources[].mount_path | string | 否 | Agent 容器内挂载路径；省略时由 Forward 根据文件名生成。 |
示例请求
curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions' \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"identity_id": "idn_xxx",
"template_id": "tmpl_support",
"title": "Customer support session",
"incremental_streaming_enabled": true,
"metadata": {
"source": "web",
"biz_id": "ticket_123"
},
"config": {
"environment_variables": {
"API_KEY": "sk-xxx",
"REGION": "cn-hangzhou"
}
},
"resources": [
{
"type": "file",
"file_id": "file_019e6a18dc09abcd",
"mount_path": "/data/input.py"
}
]
}'
示例响应
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": "Customer support session",
"incremental_streaming_enabled": true,
"metadata": {
"source": "web"
},
"config": {
"environment_variables": {
"API_KEY": "sk-xxx"
}
},
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"created_at": "2026-06-22T10:00:00Z",
"updated_at": "2026-06-22T10:00:00Z"
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | Session ID。 |
| type | string | 固定为 session。 |
| identity_id | string | Forward Identity ID。 |
| template | object | Template 摘要。 |
| source_type | string | Session 来源，直接 API 创建为 api。 |
| status | string | idle、running、rescheduling、canceling 或 terminated。 |
| incremental_streaming_enabled | boolean | 是否开启增量流式事件。 |
错误
| HTTP | Type | Code | 触发条件 |
|---|---|---|---|
| 400 | invalid_request_error | invalid_request_body | 请求体不合法。 |
| 403 | permission_error | template_access_denied | Identity 无权使用该 Template。 |
| 404 | not_found_error | identity_not_found | Identity 不存在或已删除。 |
| 404 | not_found_error | template_not_found | Template 不存在。 |
| 409 | conflict_error | identity_disabled | Identity 已停用。 |
| 422 | invalid_request_error | runtime_config_invalid | Effective 运行时配置不合法。 |
| 401 | authentication_error | authentication_required | PAT 无效或已过期。 |
注意事项
source_type由 Forward 设置，创建请求不接受该字段。incremental_streaming_enabled创建后持久化在 Session 上，之后不能修改。resources中的文件必须已通过 Files API 上传。