归档 Session Thread

POST /api/v1/forward/sessions/{session_id}/threads/{thread_id}/archive 只允许归档 role=child 且当前 status=idle 的 Thread。协调器主 Thread 不可归档。

请求参数

位置	参数	类型	是否必填	说明
Header	Authorization	string	是	`Bearer <PAT 或 SAT>`
Header	Idempotency-Key	string	否	标识一次逻辑归档尝试；建议为每次新的逻辑尝试生成唯一值。
Path	session_id	string	是	`sess_` 前缀的 Session ID。
Path	thread_id	string	是	`sthr_` 前缀的 Thread ID。

请求体为空。

示例请求

curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/threads/sthr_child_xxx/archive' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Idempotency-Key: archive-thread-20260622-001"

示例响应

{
  "id": "sthr_child_xxx",
  "type": "session_thread",
  "session_id": "sess_xxx",
  "parent_thread_id": "sthr_coordinator_xxx",
  "template_id": "tmpl_worker",
  "name": "research",
  "role": "child",
  "status": "archived",
  "stop_reason": { "type": "archive" },
  "created_by_tool_use_id": "toolu_xxx",
  "archived_at": "2026-06-22T12:00:00Z",
  "created_at": "2026-06-22T11:00:00Z",
  "updated_at": "2026-06-22T12:00:00Z"
}

已归档的 child Thread 再次归档时也返回当前 Thread 对象和 HTTP 200 OK。返回值为 Thread 对象。

错误

HTTP	Type	Code	触发条件
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。
404	`not_found`	`session_not_found`	Session 不存在或当前调用方不可见。
404	`not_found_error`	`thread_not_found`	Thread 不存在或不属于该 Session。
409	`conflict_error`	`coordinator_thread_not_archivable`	尝试归档 coordinator Thread。
409	`conflict_error`	`thread_not_idle`	child Thread 当前不是 `idle`。
502	`api_error`	`runtime_unavailable`	Thread 运行服务不可用，或归档冲突后的状态无法对账。

备注

相同 Idempotency-Key 会回放已缓存的非 5xx 响应。收到缓存的 409 thread_not_idle 后，如果 Thread 状态已改变并准备重新尝试，请使用新的 key。
对含糊的 502 runtime_unavailable 可使用相同 key 重试。
归档后应通过获取 Thread 接口确认最终状态，不要只依赖 session.thread_status_terminated Event。

归档 Session Thread

请求参数

示例请求

示例响应

错误

备注

获取 Session Thread

列出 Session Threads

​请求参数

​示例请求

​示例响应

​错误

​备注

获取 Session Thread

列出 Session Threads

请求参数

示例请求

示例响应

错误

备注