跳转到主要内容
POST /v1/sessions/{session_id}/threads/{thread_id}/archive 归档一个子线程。归档操作会将线程状态设置为 archived，取消所有待处理的 mailbox 消息，并解除对 coordinator 线程的阻塞（如有）。
只能归档 role 为 child 的线程。Coordinator 线程不可归档。

​
请求头

头部必选说明
Authorization是Bearer <PAT>

​
路径参数

参数类型必选说明
session_idstring是Session ID（sess_ 前缀）
thread_idstring是Thread ID（sthr_ 前缀）

​
示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019f00000000000000000000000000aa/threads/sthr_019f00000000000000000000000002bb/archive" \
  -H "Authorization: Bearer $QODER_PAT"

​
示例响应

HTTP 200 OK 
{
  "id": "sthr_019f00000000000000000000000002bb",
  "type": "session_thread",
  "session_id": "sess_019f00000000000000000000000000aa",
  "parent_thread_id": "sthr_019f00000000000000000000000001aa",
  "agent": {
    "id": "agent_019f000000000000000000000000002b",
    "type": "agent",
    "name": "Research Agent",
    "model": "ultimate",
    "version": 2
  },
  "agent_id": "agent_019f000000000000000000000000002b",
  "agent_version": 2,
  "name": "Research Agent",
  "role": "child",
  "status": "archived",
  "stop_reason": {"type": "archive"},
  "created_by_tool_use_id": "toolu_bdrk_01T42NPLcKrBvLJfWgGt3QMt",
  "archived_at": "2026-06-15T08:10:00.000Z",
  "created_at": "2026-06-15T08:01:00.000Z",
  "updated_at": "2026-06-15T08:10:00.000Z"
}

​
响应字段

返回归档后的 Session Thread 对象。status 变为 "archived"，stop_reason 设置为 {"type": "archive"}。

​
归档行为

归档操作会触发以下行为：
  • 线程状态设置为 archived
  • 取消所有该线程在 mailbox 中的待处理消息
  • 如果 coordinator 正在通过 Agent 工具等待该线程结果，会收到 "Agent cancelled." 的工具结果，coordinator 继续执行
  • 产生 session.thread_status_terminated 事件，stop_reason 为 {"type": "archive"}

​
错误码

HTTPtype触发条件
401authentication_errorPAT 无效或过期
404not_found_errorSession 或 Thread 不存在
409invalid_request_error尝试归档 coordinator 线程
409invalid_request_error线程状态不是 idle，无法归档
完整错误信封说明详见 错误参考。

​
相关

Managed Agents

了解 coordinator 与 child 线程的协作模型。

列出 Session Threads

查看 Session 中的所有线程及其状态。

Session Thread 对象

Session Thread 对象的完整字段参考。