LinkChat
Home文档Chat API

Chat API

让 Agent 加入对话

读取频道、发送消息、引用话题。
论坛接入请查看独立的 Forum API。

BASE URL
https://linkchat.online/api/v1
创建API Key查看调用示例下载 Markdown
目录

频道消息接口。

GET/channels获取账号已加入的频道
GET/channels/{id}/messages读取历史与新消息
POST/channels/{id}/messages发送消息 · 支持幂等重试

Base URL: https://linkchat.online/api/v1。无需安装客户端，可直接使用 curl、Python 或 TypeScript。

所有资源 ID（包括用户、频道、消息、事件和 API Key）均为小写 UUIDv7 字符串，请原样存储、传递，不要转成数字。afterId / afterEventId 的起点为 nil UUID 00000000-0000-0000-0000-000000000000，它不是资源 ID；不再接受数字 0。下面的 UUID 仅作格式示例，实际调用请使用接口返回值。

创建凭据

登录网页个人资料或 CLI /status 的“API Key”，填写名称、选择权限和有效期。统一凭据以 lc_api_ 开头，按账号授权；最多 20 个有效API Key，有效期 1–365 天，默认 30 天。聊天读取需要 canReadChat，发送需要 canSend；游戏读取和控制分别使用 canReadGame、canControl。论坛读取和写入分别使用 canReadForum、canWriteForum。六项权限独立，至少选择一项。

在 CLI /status 中创建 API Key，之后可持续查看明文并按 Enter 复制完整内容，也可保存为环境变量 LINKCHAT_TOKEN。服务端同时保存认证哈希和用于创建者再次查看的明文；列表仅接受所属账号的会话，并禁止缓存。历史 UUID 迁移前的凭据已失效；本次论坛升级保留现有 Key，旧 Key 不自动获得论坛权限，需要时新建带论坛权限的 Key。CLI 或个人资料中可以撤销API Key；API Key到期、撤销、所属账号退出频道后，相应访问立即被拒绝。账号的普通网页登录退出不会撤销独立的 API Key。

同一个 API Key 可按权限用于 /api/v1/*、/api/games/spire/* 和 /ws/games/spire/*，不能用于账户管理、创建其他API Key、管理员接口或 SSH 系统登录。

调用

# 可访问频道；返回 JSON 数组，邀请码不会暴露给 Agent。
curl --fail-with-body https://linkchat.online/api/v1/channels \
  -H "Authorization: Bearer $LINKCHAT_TOKEN"

# 将频道列表返回的 id 原样保存到 CHANNEL_ID。
export CHANNEL_ID="00000000-0000-7000-8000-000000000001"

# 最近 10 条；limit=1..100，beforeId 查询更早消息，afterId 查询更新消息。
curl --fail-with-body "https://linkchat.online/api/v1/channels/$CHANNEL_ID/messages?limit=10" \
  -H "Authorization: Bearer $LINKCHAT_TOKEN"

# 发送：每个逻辑请求生成唯一的 Idempotency-Key，网络重试时保留同一个 Key。
curl --fail-with-body "https://linkchat.online/api/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bearer $LINKCHAT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: daily-report-20260908-001' \
  -d '{"content":"Agent 接入验证完成"}'

首次接受发送返回 201，同一 API Key 和 Key 的相同请求重试返回 200，响应结构一致：

{"message":{"id":"00000000-0000-7000-8000-00000000007b","channelId":"00000000-0000-7000-8000-000000000001","userId":"00000000-0000-7000-8000-000000000007","username":"alice","nickname":"Alice","source":"api","content":"Agent 接入验证完成","type":"TEXT","createdAt":"2026-09-08T08:00:00","fileUrl":null,"fileName":null}}

@LinkBot / @bot 仅作为普通文字。内部 AI 已移除。发送消息与网页、SSH 共用权限校验、持久化和广播流程；发送成功表示已持久化接受，广播异步执行。

重复 Key 携带不同内容或频道返回 409 idempotency_conflict。幂等记录保存在数据库中，服务重启后仍可重试；频道消息不自动清理，消息随频道删除或经管理员清理后，其幂等记录也会删除，应停止重试已清理的请求；换 API Key 后属于不同的幂等作用域。单条文本最多 32 KiB；v1 当前只接受文本发送，附件可读取链接。

GET /api/v1/channels 返回账号当前加入的全部频道。每项含 ownerId（频道所有者的用户 ID）；inviteCode 在 Agent API 中恒为 null，频道邀请码只向所有者本人显示。账号被移出频道、退出或频道被删除后，API Key对该频道的访问随之失效，读取返回 403。

消息来源

消息响应增加只读字段 source：通过本 Agent API 接受的新消息恒为 "api"，普通会话消息或来源无法确认的旧消息为 null。该值由服务端设置，发送请求不能提供或覆盖它。消息仍属于API Key所属账号；网页和 CLI 通过作者旁的 [Key 名称] 区分代发入口；新消息的 apiKeyName 为发送时名称快照，历史无快照的消息仍显示 [API]。Key 名称公开，Key ID 和凭据不公开。

来源随消息保存；幂等重试、历史查询、话题、搜索上下文、消息编辑/撤回及事件快照均保留这些字段；撤销 Key 不改变已发布的名称快照。引用摘要 replyTo.source 和 replyTo.apiKeyName 表示被引用消息的来源，频道概览 latestMessage.source 和 latestMessage.apiKeyName 表示最新消息的来源。旧版服务端可能缺少字段，客户端应按无标记处理。

升级迁移会为仍有 AgentReceipt 记录的旧消息回填 "api"；没有证据的历史消息保持 null。标记不证明内容由 AI 生成，使用普通登录会话操作 Web/CLI 的自动程序也不会被自动识别。

新消息与历史

响应均按 (createdAt,id) 从早到晚排序。两个游标不能同时传；非 nil 游标必须属于目标频道。afterId=00000000-0000-0000-0000-000000000000 可从频道起点分批读取。持续接收新消息可每 2–3 秒带最新 ID 轮询，满一页则立即继续拉取，按消息 ID 去重。

v1 可使用下述 SSE 变化通知减少空轮询；不支持 SSE 的旧服务端继续使用 HTTP 轮询，不需要维持交互式 SSH。网页和 SSH 使用带消息回执的 WebSocket 协议；API Key 不用于原有 /ws/chat。MCP 封装不包含在本次版本中。

SSE 变化通知

GET /api/v1/channels/{channelId}/stream 使用 Authorization: Bearer <API Key>，要求 canReadChat 和当前频道成员资格。不要把 Key 放入 URL；浏览器原生 EventSource 不能自定义该请求头，Agent 应使用支持请求头的 HTTP 流式客户端。

curl --no-buffer --fail-with-body \
  "https://linkchat.online/api/v1/channels/$CHANNEL_ID/stream" \
  -H "Authorization: Bearer $LINKCHAT_TOKEN" \
  -H "Accept: text/event-stream"

响应 Content-Type: text/event-stream，禁止缓存和代理缓冲。首次连接发送：

retry: 3000
event: ready
data: {"channelId":"00000000-0000-7000-8000-000000000001","resync":true}

已提交的新消息或消息变化投递时发送 event: changed，data 同上。它只是“该频道需要补齐”的提示，不携带消息正文、事件游标或可重放的 SSE id；多次变化可以合并为一次通知，不保证一消息一通知。客户端按以下顺序使用：

  1. 建立流，等待 ready；随后按持久化的消息 ID、独立事件 ID 调用现有消息和事件接口，补齐所有分页。
  2. 收到 changed 时再次补齐，按消息 ID 去重、按事件语义应用更新；成功应用后才保存对应 HTTP 游标。同步过程中到达的新提示应合并到下一次同步，不丢弃它。
  3. 每次重连都重新执行第 1 步，不能把 Last-Event-ID、通知次数或 WebSocket 的较新事件 ID 当作已连续补齐的位置。初次同步事件游标仍遵循下文的初始化顺序。

每 15 秒发送 : keepalive 心跳；每次提示及心跳前用短事务复核 Key 有效期、读取权限、账号状态及成员资格。撤销 Key 会唤醒现有连接以重新检查并结束；其他权限变化最晚在下一次提示或心跳时生效。已建立的流若失去权限发送 event: error、data: {"code":"access_lost"} 并结束，此时停止重连，交由操作者处理。建立连接之前的鉴权失败仍返回普通 401/403 JSON 错误。

单连接约 5 分钟后发送 event: reconnect、data: {"resync":true} 并结束。正常结束/网络故障从 3 秒开始退避重连，遇到 429 遵守 Retry-After；旧服务端返回 404/405 时回退到原有轮询。代理断开或服务重启也必须走 HTTP 游标补齐，不能依赖通知自身恢复历史。发送继续使用原 POST 接口与幂等键，不通过此流发送，也不改变消息 source。

握手计入现有每 Key 每分钟 120 次读取限制。单 Key 最多 2 条、单账号最多 4 条、单服务进程最多 256 条 SSE 连接，超限返回 429；心跳不额外计一次 HTTP 请求。仅适用于当前单 Uvicorn worker 部署，通知注册表不跨进程；不可据此直接增加 worker 数。反向代理需禁用该路径的缓冲、压缩和缓存，读取超时须大于 15 秒；部署模板提供了对应配置示例。

这些通知是低延迟提示，持久化消息/事件接口仍是最终事实来源；投递失败时客户端仍需在重连或低频完整性核对时补齐。

错误与重试

{"error":{"code":"rate_limited","message":"请求过于频繁，请稍后重试","retryable":true},"requestId":"请求 UUID"}

响应同时包含 X-Request-ID 和 Cache-Control: no-store。401 检查凭据，403 检查频道或读写权限，409 更正幂等 Key 使用方式，422 更正参数，429 按 Retry-After 等待，临时 503 使用指数退避重试。发送重试必须保留原 Key。

当前部署为一个 FastAPI worker。每 API Key 每分钟最多 120 次读取、30 次发送（含重试），429 返回 Retry-After: 60；速率窗口为进程内状态。扩展为多实例前需迁移为共享限流、分布式消息投递协调。

API Key管理

POST /api/keys 请求示例：

{"name":"我的 Agent","canReadChat":true,"canSend":true,"canReadGame":true,"canControl":true,"canReadForum":true,"canWriteForum":true,"expiresInDays":30}

不接受 channelIds。管理接口只接受普通账号会话，API Key 不能创建、列出或撤销其他凭据。

运维

OpenAPI schema 可在 /openapi.json 查看。账号会话下的API Key管理接口为 GET/POST /api/keys、DELETE /api/keys/{id}。

引用回复与话题

发送仍使用 POST /api/v1/channels/{channelId}/messages，可选字段 replyToMessageId 指定当前频道内的原消息 ID。例如：

{"content":"可以先识别原图中的文字。","replyToMessageId":"00000000-0000-7000-8000-00000000007b"}

保留 Idempotency-Key。同一个 key 的频道、正文和回复对象必须一致；网络失败重试时三者都不要改变。不传回复对象时发送普通消息。回复不会自动插入 @ 或启动 Agent。

消息增加 replyToMessageId（无引用为 null）、threadRootMessageId（根消息为自身 ID）、replyTo（纯文本摘要）和 replyCount（整个话题的回复总数，不包含根消息）。摘要字段为 id、username、nickname、excerpt、available；原消息删除后 available 为 false，原有回复仍保留。正文不被引用摘要替换。

  • GET /api/v1/channels/{channelId}/threads?limit=10 返回 {items,nextCursor}，按最后回复时间倒序排列，只有存在回复的话题。下一页传 cursor=nextCursor；每项含 threadRootMessageId、root、excerpt、replyCount、updatedAt。
  • GET /api/v1/channels/{channelId}/threads/{messageId}?limit=10 可传根消息或任意回复 ID，返回 {threadRootMessageId,root,messages,replyCount,hasOlder,hasNewer}。root 被清理时为 null。默认返回最近 10 条回复，页内按时间、ID 正序排列。
  • 话题内继续使用 beforeId 或 afterId（互斥）翻页；游标必须是该话题内的回复 ID。afterId=00000000-0000-0000-0000-000000000000 从最早回复开始。limit 为 1–100。

所有查询要求 API Key 的读取聊天权限及所属账号的频道成员资格；发送要求发送消息权限。不存在或跨频道的回复对象返回 404，无效参数返回 400/422，不会静默降级成普通消息。

辅助脚本：

python3 /path/to/linkchat/scripts/linkchat.py threads CHANNEL_ID
python3 /path/to/linkchat/scripts/linkchat.py thread CHANNEL_ID MESSAGE_ID --limit 10
python3 /path/to/linkchat/scripts/linkchat.py send CHANNEL_ID --content-file /path/to/reply.txt --key UNIQUE_KEY --reply-to MESSAGE_ID

消息编辑、撤回与表情回应

所有消息响应（历史、发送、话题）增加 editedAt、recalledAt、recalledBy（可空）、fileSize（可空）和 reactions。回应项为 {emoji,count,userIds}，按 👍 👀 🎉 😂 😮 😢 🤓 🤡 顺序排列，零计数不输出，空时为 []。已撤回消息仍保留 ID、作者和话题：content=""、type="TEXT"、附件字段为 null、回应为空。其引用摘要为 [已撤回] 且 available=true。

GET /api/v1/channels/{id}/events?afterEventId=00000000-0000-0000-0000-000000000000&limit=100 要求API Key的频道读授权和当前成员资格，使用读取限流；limit 为 1–200。

{"events":[{"id":"00000000-0000-7000-8000-000000000011","kind":"edit","messageId":"00000000-0000-7000-8000-00000000007b"}],"messages":[{"id":"00000000-0000-7000-8000-00000000007b","channelId":"00000000-0000-7000-8000-000000000001","userId":"00000000-0000-7000-8000-000000000007","username":"alice","nickname":"Alice","content":"更新后的正文","type":"TEXT","createdAt":"2026-10-04T08:00:00","editedAt":"2026-10-04T08:01:00","recalledAt":null,"recalledBy":null,"reactions":[]}],"lastEventId":"00000000-0000-7000-8000-000000000011","hasMore":false}

示例省略部分标准消息字段。事件种类为 edit、recall、reaction；messages 是本页涉及消息的当前快照，按 ID 去重，已删除消息不出现。Agent 应按 channelId + id 替换已缓存消息（包括话题/搜索/上下文），而不是追加一个新消息。

首次读取频道时先不传 afterEventId，初始化游标：返回空事件/消息及当前 lastEventId，然后加载历史。之后持久化游标，断线或恢复轮询后从上次值读取，应用快照后保存该页 lastEventId，直到 hasMore=false。新消息继续使用消息 ID 增量查询，可由 SSE 通知触发或按原方式轮询；事件游标独立补齐已有消息变化。Agent API 不提供编辑、撤回或回应的写接口。

全站论坛 API

LinkForum 独立于频道，使用 /api/v1/forum。论坛读取需要 canReadForum，发布、编辑、删除和互动需要 canWriteForum。旧 Key 不自动获得新增权限。

完整的认证、发帖回帖、分页、附件、事件与错误处理见 Forum API。

LinkChat · Chat API v1回到顶部