API 参考

基地址 https://ai.syctra.com/api/v1 · 除标注公开外，所有接口都需要 Authorization: Bearer <token>。认证、错误、限流与安全请见 API 与原生集成。

运行 —— 与智能体对话

`POST /chat`

启动一次持久运行并立即返回。

字段	类型	默认	说明
`message`	string	—	必填。你要智能体做的事
`app_name`	string	`"main"`	目标智能体。任意目录键（`interactive`、`data_copilot`、`contract_review_dz`、`slide_master`、`finance_master`…）或 `custom_<id>`（你自建的）
`session_id`	uuid	新建	继续已有会话；留空则新开一个
`attachments`	string[]	—	来自 `POST /uploads` 的上传 ID
`kb_ids`	string[]	—	运行期间智能体可检索的知识库
`kb_enhance`	bool	`false`	用大模型改写 RAG 答案（更慢、更充实）
`plan`	bool	`false`	计划模式：智能体先写步骤计划再执行，并发出 `plan` / `plan_step`
`model`	string	账号默认	模型目录键 —— 见 `GET /models`
`reasoning`	bool	`false`	回答前进行更长时间的推理
`data_workspace_id`	uuid	—	要操作的 Data Lab 工作区
`client_tz`	string	UTC	IANA 时区，如 `"Asia/Shanghai"`
`idempotency_key`	string	—	可安全重放：同一个 key 返回同一次运行

{ "run_id": "…", "session_id": "…", "cursor": 0, "resumed": false,
  "status": "running", "queue_seq": 0 }

status 为 running；会话忙时为 queued（前一次结束后自动开始）；或 blocked。

方法	路径	用途
`POST`	`/tasks`	与 `/chat` 相同但显式后台化 —— 适合批处理
`GET`	`/runs/{run_id}/events`	运行的 SSE 流（见下）
`POST`	`/runs/{run_id}/respond`	回答智能体的提问（`user_choice`、`quiz`、审批）
`POST`	`/runs/{run_id}/cancel`	停止运行
`GET`	`/sessions/{id}/queue`	查看会话待办队列
`POST`	`/sessions/{id}/queue/resume`	恢复因失败而暂停的队列

`GET /runs/{run_id}/events` —— 事件流

text/event-stream。每个事件带 id（单调递增的 seq）、event（类型）和 data（JSON）。 可续传：用 Last-Event-ID: <seq> 或 ?after=<seq> 重连，游标之后的内容会从持久存储回放 —— 不丢工作，也不重复计费。

分组	事件
回答	`token`（文本片段）· `usage`（token 计数）· `done` · `error`
工具	`tool_call` · `tool_result` · `sandbox_stdout`
计划	`plan`（有序步骤）· `plan_step`（序号 + 状态）
文档	`document_start` · `document_delta` · `document_end`（携带 `artifact_id`）
交付物	`artifact` · `file`（PDF/DOCX/PPTX/XLSX）· `image` · `slides` · `webpage` · `chart` · `sheet`
研究	`sources`（网页结果）· `graph`（知识图谱）· `browser`（浏览器操作截图）· `maps`
人工介入	`user_choice` · `choice_answer` · `quiz` · `approval`（等待你确认的动作）
通信	`email_draft` · `email_sent` · `social` · `call`
法务工作室	`dossier` · `timeline` · `doc_summary` · `findings` · `contract` · `clause` · `contract_compare` · `consultation` · `legal_issues` · `ref_check` · `deadline` · `watch_synthesis` · `watch_change` · `watch_diff`
招聘	`candidate` · `iv_job` · `iv_candidate` · `iv_questions` · `iv_grid` · `iv_answers` · `iv_ask` · `iv_plan`
业务	`prospect` · `cerfa` · `exhibition` · `finance` · `site_map` · `site_pack`

只要纯文本回答，消费 token、done、error 即可；其余是结构化卡片，可渲染也可忽略。遇到未知事件类型应跳过而不是当作错误 —— 新类型会不断加入。

方法	路径	用途
`GET`	`/models`	你账号可用的模型目录
`GET`	`/sessions`	列出会话
`GET`	`/sessions/{id}`	单个会话及其最近事件
`PATCH` `DELETE`	`/sessions/{id}`	重命名 / 删除
`GET`	`/sessions/{id}/messages`	完整消息历史
`GET`	`/sessions/{id}/artifacts`	该会话产出的全部文件
`POST`	`/sessions/{id}/branch`	从某个节点分叉会话
`POST`	`/sessions/{id}/truncate`	将会话截断到某条消息
`GET` `POST`	`/sessions/{id}/versions`	产物版本历史 / 还原
`GET`	`/sessions/search?q=`	全文搜索你的会话

文件

方法	路径	用途
`POST`	`/uploads`	`{filename, content_base64, mime, session_id?}` → `{upload_id}`。自动解析（OCR、视觉、转写）。单文件最大 200 MB
`GET`	`/uploads/{id}`	解析状态与抽取文本
`GET`	`/uploads/{id}/raw`	原始字节
`POST`	`/artifacts`	用你自己的内容创建产物
`GET`	`/artifacts/{id}`	下载生成的文件
`POST`	`/export`	将 Markdown/HTML 渲染为 PDF、DOCX 或 PPTX
`POST`	`/export-text`	纯文本导出

把上传 ID 放进 attachments 即可附加到某次运行。支持：PDF、Office、图片、音频、视频、 CSV/Excel、ZIP（递归解包）。

知识库（RAG）

方法	路径	用途
`POST` `GET`	`/kb`	创建 / 列出知识库
`PATCH` `DELETE`	`/kb/{id}`	重命名 / 删除
`GET` `POST`	`/kb/{id}/documents`	列出 / 添加文档（异步入库）
`POST`	`/kb/query/stream`	流式查询（见下）
`GET` `PUT`	`/kb/{id}/config`	检索配置（法务 / 企业 / 时间线 / 通用）、全文检索语言、预算。`PUT` 会重写所有字段 —— 请提交完整对象
`GET`	`/kb/{id}/chunks` · `/entities` · `/graph`	查看索引、抽取实体、知识图谱
`GET`	`/kb/{id}/file/{doc_id}` · `/image/{image_id}`	源文档 / 抽取的图片
`POST` `GET`	`/kb/{id}/conversations`	多轮 RAG 会话
`GET`	`/kb/{id}/conversations/{cid}/messages`	会话历史
`GET` `POST` `DELETE`	`/kb/{id}/connectors` …	从外部源同步；`/kb/connectors/catalog` 列出可用连接器
`POST` `GET` `DELETE`	`/kb/{id}/share`	发布公开查询链接
`GET`	`/kb/pricing`	每次查询的计费模型

curl -N -X POST https://ai.syctra.com/api/v1/kb/query/stream \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
    "kb_id": "…", "q": "满 12 个月后适用哪些解约条款？",
    "mode": "full", "cite": true, "enhance": false, "agent": false, "top_k": 20
  }'

字段	取值	说明
`mode`	`auto` · `quick` · `full` · `deep` · `graph_local` · `graph_global`	检索深度。`auto` 依问题自动选择
`cite`	bool	行内 `[N]` 引用及来源 ID
`enhance`	bool	用大模型改写答案
`agent`	bool	检索前先拆解多问题
`doc_id`	string	只在单个文档内检索
`conversation_id`	uuid	继续多轮会话

自定义智能体

方法	路径	用途
`GET`	`/agent-tools`	可为智能体开启的能力目录
`GET` `POST`	`/agents/custom`	列出 / 创建
`GET` `PUT` `DELETE`	`/agents/custom/{id}`	读取 / 修改 / 删除
`POST`	`/agents/custom/persona`	从上传的文字中提炼人物设定
`GET`	`/marketplace` · `/marketplace/{id}`	已发布的智能体
`POST`	`/marketplace/{id}/install` · `/publish` · `/unpublish`	安装 / 发布 / 下架

{
  "name": "招投标分析师", "emoji": "📑",
  "description": "阅读招标文件并给出投或不投的结论",
  "instruction": "你是一名公共采购分析师…",
  "tool_keys": ["web", "deep_research", "documents", "knowledge_base", "database"],
  "model": "standard", "visibility": "private",
  "examples": ["分析这份招标文件"], "tags": ["采购"]
}

能力键：knowledge_base · web · deep_research · agent_team · computer_use · algerian_law · documents · slides · charts · images · webpage · code · quiz · email · planning · scraping · prospecting · linkedin · meta · obsidian · knowledge_graph · scheduling · workspace_files · data_engineering · database · n8n · stripe · paypal · notion · github · gitlab · elevenlabs · microsoft · atlassian · slack · s3 · apify · mcp_remote。

运行方式与其他智能体一致：POST /chat 传 "app_name": "custom_<id>"。

调度器

方法	路径	用途
`GET` `POST`	`/cron`	列出 / 创建定时运行
`PATCH` `DELETE`	`/cron/{id}`	暂停、修改、删除
`POST`	`/cron/{id}/run`	立即执行一次

{ "name": "周一竞品监测", "cron_expr": "0 8 * * 1",
  "timezone": "Asia/Shanghai", "prompt": "总结上周的动向…",
  "app_name": "main", "delivery_email": "team@acme.com" }

标准 5 字段 cron。delivery_email 会把最终答案发到邮箱；留空则不发送。

Data Lab

方法	路径	用途
`GET` `POST`	`/data/workspaces`	列出 / 创建持久 DuckDB 工作区
`PATCH` `DELETE`	`/data/workspaces/{id}`	重命名 / 删除
`POST`	`/data/workspaces/{id}/ingest`	导入 Excel/CSV —— 支持杂乱表格、多行表头、一张表里多个数据块
`GET`	`/data/workspaces/{id}/tables` · `/files`	查看表结构与来源
`POST`	`/data/workspaces/{id}/query`	在工作区上执行 SQL
`DELETE`	`/data/workspaces/{id}/tables/{table}`	删除表

智能体集群

方法	路径	用途
`GET`	`/swarm/api/teams` · `/catalogue` · `/health`	可用团队与引擎状态
`POST`	`/swarm/api/run`	启动多智能体运行
`GET`	`/swarm/api/run/{id}/stream`	SSE 进度
`POST`	`/swarm/api/run/{id}/cancel`	终止
`GET`	`/swarm/api/dossiers` · `/{id}` · `/{id}/file/{name}`	产出的档案及其文件
`POST`	`/swarm/api/convert` · `/template/inspect`	转换输出 / 检查演示模板

文档与项目

方法	路径	用途
`GET`	`/docspace`	文件夹树与文档
`POST` `PATCH` `DELETE`	`/folders`, `/folders/{id}`	管理文件夹
`POST` `PATCH` `DELETE`	`/documents`, `/documents/{id}`	管理文档
`GET`	`/documents/{id}/content`	读取内容
`POST`	`/documents/{id}/attach`	把文档挂到会话上
`POST`	`/docspace/import-zip`	批量导入
`GET` `POST`	`/projects`, `/projects/{id}`	汇总会话与文件的工作区
`POST` `GET` `DELETE`	`/projects/{id}/members`	项目权限

分享（公开链接）

方法	路径	用途
`POST` `GET` `DELETE`	`/sessions/{id}/share`	发布会话
`GET`	`/shared/{slug}`	公开读取已分享会话
`GET`	`/shared/{slug}/artifacts/{id}`	公开已分享会话中的产物
`GET` `POST`	`/shared/{slug}/comments`	公开评论区
`POST`	`/shared/{slug}/clone`	把分享的会话复制到自己账号
`POST` `GET` `DELETE`	`/docshare`	分享文档 / 文件夹
`GET`	`/shared-doc/{slug}`	公开已分享文档
`GET`	`/shared-kb/{slug}` · `POST /shared-kb/{slug}/query/stream`	公开知识库链接，查询计费给所有者

公开链接是未列出的 URL，不是认证。凡是你发布的内容，任何拿到链接的人都能读取 —— 而对已分享知识库的查询会计费给你。用对应的 DELETE 撤销。

可嵌入挂件

在 集成 → Widget 中创建挂件，然后在你的站点粘贴一行：

<script src="https://ai.syctra.com/embed.js" data-key="pk_live_…" async></script>

可选 data-position="bottom-left" | "bottom-right"。挂件调用的是 /embed-api 下的一套独立公开接口 —— 公开密钥不是 API 密钥，读不到你的账号：

方法	路径	用途
`GET`	`/embed-api/config/{public_key}`	公开挂件配置
`POST`	`/embed-api/chat`	公开访客消息
`GET`	`/embed-api/runs/{run_id}/events`	公开回答流
`GET`	`/embed-api/history/{public_key}/{visitor_id}`	公开访客历史
`GET` `POST` `PATCH` `DELETE`	`/embed-widgets`	所有者管理（需认证）

/embed-api/* 与 /scim/v2/* 位于域名根路径下，不在 /api/v1 之下 —— 例如 https://ai.syctra.com/embed-api/chat。

只有被列入公开白名单的智能体才能绑定到挂件，访客流量按挂件限流，每次对话都计费给所属组织。发布前请限制允许的来源域名。

团队、组织与账号供给

方法	路径	用途
`GET`	`/enterprise` · `/enterprise/analytics` · `/enterprise/retention`	组织、用量、留存策略
`POST` `DELETE`	`/enterprise/teams`, `/teams/{id}`	管理团队
`POST` `DELETE`	`/enterprise/teams/{id}/members…`	成员关系
`POST` `DELETE`	`/enterprise/teams/{id}/grants`	团队可使用哪些智能体
`POST`	`/enterprise/teams/{id}/invite` · `/invites/revoke` · `/invites/resend`	邀请
`GET` `POST`	`/invite/{token}`, `/invite/{token}/accept`	公开接受邀请
`GET` `PUT` `DELETE`	`/enterprise/sso`	SAML / OIDC 单点登录
`POST`	`/enterprise/scim-token`	签发 SCIM 供给令牌
`GET`	`/me/caps` · `/me/teams` · `POST /me/active-team`	调用者的权限与团队
`GET` `POST` `DELETE`	`/teams`, `/groups`, `/share-targets`	轻量团队、群组、分享目标

SCIM 2.0 位于 https://ai.syctra.com/scim/v2，使用独立令牌（不是 API 密钥）： GET|POST /Users、GET|PUT|PATCH|DELETE /Users/{id}、GET /Groups。

账号、通知与隐私

方法	路径	用途
`GET` `PATCH`	`/auth/me`	个人资料
`POST`	`/auth/change-password` · `/auth/logout`	凭据 / 退出
`GET`	`/balance`	额度余额
`GET` `POST`	`/notifications`, `/notifications/read`	站内通知
`PUT`	`/me/notify-email` · `/me/low-balance-pct`	通知偏好
`GET` `POST`	`/push/vapid-key`, `/push/subscribe`	Web Push 订阅
`GET` `DELETE` `PUT`	`/memory`, `/memory/{id}`, `/memory/settings`	长期记忆：查看、删除、关闭
`GET`	`/account/export`	GDPR 导出你拥有的全部数据
`DELETE`	`/account`	GDPR 删除账号及其数据
`GET` `POST`	`/approvals`, `/approvals/{id}/decide`	批准或拒绝受管控动作
`GET` `PUT`	`/approval-settings`	哪些能力需要人工审批

其他接口

方法	路径	用途
`GET` `POST` `DELETE`	`/deadlines…`	法务期限日程
`POST` `GET` `DELETE`	`/meetings…`	会议转写与纪要
`POST` `GET` `DELETE`	`/dubbings…`, `GET /dubbing/languages`	视频 / 音频配音任务
`POST` `GET` `DELETE`	`/email-compose`, `/email-templates`	已撰写邮件与模板
`POST`	`/email/send`	通过平台发送邮件
`GET` `POST` `DELETE`	`/prompts`	保存的提示词
`POST`	`/feedback` · `/message-feedback`	产品反馈与单条回答反馈
`GET`	`/healthz` · `/readyz` · `/metrics`	公开存活、就绪、Prometheus 指标

集成注意事项

目前没有出站 webhook。 跟踪长任务请保持 SSE 连接，或轮询 GET /sessions/{id} —— 两种方式下运行都不会因你断开而中止。
轮询要克制。 优先用 SSE；确需轮询时请带上你已持有的 cursor。
保存游标。 持久化你处理过的最后一个 seq，能让集成在崩溃后安全恢复。
固定智能体。 app_name 决定行为、成本与可用工具 —— 请显式指定，别依赖默认的 main。
优先处理 402 与 429。 这是健康集成在生产环境中真正会遇到的两个错误；其他错误通常说明载荷有问题。