Halo

简体中文

English

简体中文

English

外观

API：会话 ​

Halo HTTP API 会话接口：发起一轮任务、停止运行、查看进行中的会话，列出、读取、重命名、星标和删除会话。

会话是工作区里你和 Halo 助手之间的对话线程。API 按工作区组织会话，路径里的工作区写作 spaces。用这些接口在会话中发起任务、跟进和停止运行，并管理会话列表。与数字人的聊天在 API：数字人 页。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 $HALO_URL 和 $HALO_TOKEN 按快速上手设置；地址、鉴权和错误约定见 HTTP API 概览。

操作端点
查询 Halo 是否仍在某个会话中生成回复GET /api/agent/generating/:conversationId
在会话中发起一轮新任务POST /api/agent/message
列出 Halo 正在处理的会话GET /api/agent/sessions
停止 Halo 在会话中正在做的事POST /api/agent/stop
列出会话可用的按需能力POST /api/agent/toolsets/list
列出工作区中的会话GET /api/spaces/:spaceId/conversations
新建空会话POST /api/spaces/:spaceId/conversations
读取会话及其消息GET /api/spaces/:spaceId/conversations/:conversationId
修改会话标题或元数据PUT /api/spaces/:spaceId/conversations/:conversationId
删除会话 不可撤销DELETE /api/spaces/:spaceId/conversations/:conversationId
读取一条消息背后的思考过程和工具调用GET /api/spaces/:spaceId/conversations/:conversationId/messages/:messageId/thoughts
星标或取消星标会话POST /api/spaces/:spaceId/conversations/:conversationId/star

查询 Halo 是否仍在某个会话中生成回复 ​

GET /api/agent/generating/:conversationId 助手可调用

路径参数

名称说明
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。

响应

ts
{success:true,data:boolean}

示例

bash
curl -s "$HALO_URL/api/agent/generating/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"

在会话中发起一轮新任务 ​

POST /api/agent/message 助手可调用

  • Starts Halo working in the conversation and returns as soon as the turn is accepted: success: true means accepted, not answered. The reply is written afterwards.
  • Follow the reply over the WebSocket after subscribing to the conversation, or poll GET /api/agent/generating/:conversationId with a growing interval (2 s, then double) and read the conversation when it is done.
  • Optional body fields: resumeSessionId, thinkingEnabled (boolean), reasoningEffort (off, minimal, low, medium, high, xhigh or max; overrides thinkingEnabled, but a level the user chose for this conversation wins), knowledgeBaseId, images (base64 attachments; the whole JSON body must stay under 100 KB).
  • Start work in a conversation you created with POST /api/spaces/:spaceId/conversations, so your turn never interrupts one the user is having.
  • A turn can stop to ask the user a question. The user answers it in the Halo app, and the turn waits until then.

请求体

json
{
  "spaceId": "<spaceId>",
  "conversationId": "<conversationId>",
  "message": "Summarize the activity log"
}

响应

ts
{success:true}  // no data — the turn runs after the call returns

示例

bash
curl -sX POST "$HALO_URL/api/agent/message" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>","conversationId":"<conversationId>","message":"Summarize the activity log"}'

列出 Halo 正在处理的会话 ​

GET /api/agent/sessions 助手可调用

响应

ts
{success:true,data:string[]}  // array of conversationId, each one currently generating a reply

示例

bash
curl -s "$HALO_URL/api/agent/sessions" \
  -H "Authorization: Bearer $HALO_TOKEN"

停止 Halo 在会话中正在做的事 ​

POST /api/agent/stop 助手可调用

  • conversationId is optional. Leave it out (or send {}) to stop everything Halo is doing.

请求体

json
{
  "conversationId": "<conversationId>"
}

响应

ts
{success:true}

示例

bash
curl -sX POST "$HALO_URL/api/agent/stop" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"<conversationId>"}'

列出会话可用的按需能力 ​

POST /api/agent/toolsets/list 助手可调用

  • Read-only: lists the on-demand capabilities (toolsets in the API) a conversation can use and whether each is open. The user opens and closes them in the composer under ＋ › Capabilities.

请求体

json
{
  "spaceId": "<spaceId>",
  "conversationId": "<conversationId>"
}

响应

ts
{success:true,data:[{id:string,displayName:string,summary:string,open:boolean}]}

示例

bash
curl -sX POST "$HALO_URL/api/agent/toolsets/list" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>","conversationId":"<conversationId>"}'

列出工作区中的会话 ​

GET /api/spaces/:spaceId/conversations 助手可调用

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。

响应

json
{
  "success": true,
  "data": [
    {
      "id": "<uuid>",
      "title": "…",
      "starred": false
    }
  ]
}

示例

bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN"

新建空会话 ​

POST /api/spaces/:spaceId/conversations 助手可调用

  • Creates an empty conversation. To make Halo work in it, call POST /api/agent/message with its id.
  • Optional body field reasoningEffort: off, minimal, low, medium, high, xhigh or max — how hard the model thinks. Leave it out to follow the model's configured effort.
  • Optional body field ephemeral (boolean): for a view that shows the transcript itself. The conversation is left out of every list and search, and deleted at the next start of Halo unless deleted before. Leave it out for a conversation the user should see.

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。

请求体

json
{
  "title": "Weekly report"
}

响应

json
{
  "success": true,
  "data": {
    "id": "<uuid>",
    "title": "Weekly report"
  }
}

示例

bash
curl -sX POST "$HALO_URL/api/spaces/<spaceId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Weekly report"}'

读取会话及其消息 ​

GET /api/spaces/:spaceId/conversations/:conversationId 助手可调用

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。

查询参数：from

响应

json
{
  "success": true,
  "data": {
    "id": "<uuid>",
    "messages": [
      {
        "id": "<uuid>",
        "role": "user",
        "content": "…"
      }
    ]
  }
}

示例

bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"

修改会话标题或元数据 ​

PUT /api/spaces/:spaceId/conversations/:conversationId 可撤销 助手可调用

  • modelSourceId + modelId (always both; sourceId is a uuid from GET /api/config) pin the account and model the conversation runs on. A pin naming an account that no longer exists is not rejected: the conversation runs on the current global account until it is pinned again.

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。

请求体

json
{
  "title": "Renamed conversation"
}

响应

ts
{"success":true,"data":{...updated conversation}}

示例

bash
curl -sX PUT "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Renamed conversation"}'

删除会话 ​

DELETE /api/spaces/:spaceId/conversations/:conversationId 不可撤销 助手可调用

不可撤销

执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。

  • Removes the conversation file and its reasoning history from disk. There is no backup.

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。

响应

json
{
  "success": true
}

示例

bash
curl -sX DELETE "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"

读取一条消息背后的思考过程和工具调用 ​

GET /api/spaces/:spaceId/conversations/:conversationId/messages/:messageId/thoughts 助手可调用

  • Wrong ids return an empty array, not a 404 — an empty result does not prove the message had no thoughts.
  • toolInput and toolOutput are the raw arguments and results of that turn, so this gets long fast. Read it to diagnose what Halo actually did, not as a way to read a conversation.

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。
messageId消息 ID，来自 GET /api/spaces/:spaceId/conversations/:conversationId 返回的消息列表。

响应

json
{
  "success": true,
  "data": [
    {
      "id": "…",
      "type": "…",
      "content": "…",
      "timestamp": "…",
      "toolName": "…",
      "toolInput": {},
      "toolOutput": "…"
    }
  ]
}

示例

bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>/messages/<messageId>/thoughts" \
  -H "Authorization: Bearer $HALO_TOKEN"

星标或取消星标会话 ​

POST /api/spaces/:spaceId/conversations/:conversationId/star 可撤销 助手可调用

路径参数

名称说明
spaceId工作区 ID，来自 GET /api/spaces。Halo 工作区的 ID 固定为 halo-temp。
conversationId会话 ID，来自 GET /api/spaces/:spaceId/conversations。

请求体

json
{
  "starred": true
}

响应

json
{
  "success": true
}

示例

bash
curl -sX POST "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>/star" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"starred":true}'

基于 MIT 协议开源 · Open source under the MIT license

© 2025 Halo · hello-halo.cc