API 参考

TavernHeadless 后端提供 RESTful 风格的 HTTP API，返回 JSON。本节按资源分类，详细列出每个接口的路径、参数、请求体、响应体和错误码。

基础信息

项目	值
基础 URL	http://localhost:3000
OpenAPI 版本	3.0.3
API 版本	0.2.0-beta.3
OpenAPI JSON	GET /openapi.json
Swagger UI	GET /docs/
中文文档	GET /docs-zh
英文文档	GET /docs-en
Health	GET /health
Version	GET /version

认证

通过 .env 中的 AUTH_MODE 控制认证模式：

模式	说明	请求头
off	无认证（默认）	无需携带
api_key	API Key	Authorization: Bearer <key> 或 x-api-key: <key>
jwt	JWT	Authorization: Bearer <token>

AUTH_MODE=off 只应用于本地开发。当前服务会在 NODE_ENV=production && AUTH_MODE=off 时直接拒绝启动。

api_key 模式下，可在 AUTH_API_KEYS 中配置多个 key，逗号分隔。若同时启用 ACCOUNT_MODE=multi，还必须配置 AUTH_API_KEY_ACCOUNTS，把每个 key 映射到具体账号。

jwt 模式下，需要设置 AUTH_JWT_SECRET。若同时启用 ACCOUNT_MODE=multi，JWT 还必须携带账号 claim，默认字段名为 account_id，也可以通过 AUTH_JWT_ACCOUNT_CLAIM 改名。

多账号隔离时，ACCOUNT_MODE=multi，各资源自动按账号隔离；该模式不能与 AUTH_MODE=off 一起使用。

以下 public path 始终按匿名请求处理，不会继承管理员上下文：

• GET /health
• GET /version
• GET /openapi.json
• GET /docs
• GET /docs/*

认证后的授权真相来源是数据库中的账号行：

• accounts.role 决定管理员能力
• accounts.status 决定账号是否可用
• JWT 的 role claim 不直接授予管理员权限

WebSocket 也遵循相同边界：

• /ws?session_id=... 会在握手期校验 session ownership
• 不带 session_id 的全局订阅仅允许数据库 role=admin 的账号建立

响应格式

成功响应

除非某一页另有说明，成功响应都包裹在 data 字段中：

{
  "data": {}
}

两类已知例外，以各自页面的说明为准：

• Workspace / Project 路由族（含 Projects、Agent Types、Agent Bindings、Agent Jobs、NodeGraphs、Project Settings、Derived Outputs、Inbox）不使用 data 包裹，而是返回 items / item 或直接返回对象。
• Effective Config 不使用 data 包裹，且响应字段使用 camelCase。

列表接口额外包含 meta 字段：

{
  "data": [],
  "meta": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "has_more": true,
    "sort_by": "created_at",
    "sort_order": "desc"
  }
}

除非某一页另有说明，接口传输的 JSON 字段名统一使用 snake_case。官方 SDK 在少数高层接口中会提供 camelCase 映射，但原始 REST 响应、OpenAPI 和本文档都以 snake_case 为准。

错误响应

{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}

常见 HTTP 状态码：

状态码	含义
200	成功
201	创建成功
204	删除成功（无响应体）
400	请求参数错误
401	未认证，或认证后的账号不存在
403	账号被禁用，或缺少系统级能力
404	资源不存在，或资源存在但不属于当前账号
409	冲突（如账号内重名、乐观锁失败）
410	资源逻辑上已删除
413	请求体过大
500	服务端错误
502	上游 LLM 服务错误
503	服务不可用或暂时繁忙
504	上游生成超时

Workspace / Project 兼容与角色规则

服务端已经在数据库和服务层为新数据补齐 Workspace / Project 归属。旧 API 仍保持兼容：

• 普通客户端创建和使用会话时，不需要传 workspace_id 或 project_id。
• POST /sessions 支持可选请求字段 project_id。这是高级字段，只在调用方已经知道目标 Project 时使用。
• 如果 POST /sessions 不传 project_id，服务端会使用当前账号默认 Workspace，并为该 Session 创建 session_default Project。
• Session 的默认响应不新增 workspace_id 和 project_id 字段。GET /sessions/:id/scope 用于显式读取归属。
• owner 可以读写 Project 下资源；observer 只能读取可读资源；deriver 可以写入 Derived Output、创建 Inbox 条目，但不能修改主 Session。
• 非成员访问 Project 下资源时，服务端隐藏资源存在性。Project API 通常返回 404 project_not_found，旧资源路由通常返回 404 not_found。
• 当前不开放 GET /sessions?workspace_id=...、GET /sessions?project_id=... 或 include=workspace,project。
• 旧的 global 配置语义保持不变，表示“当前账号默认 Workspace 的默认配置”。

这一族资源的完整路由清单、角色矩阵和详细文档入口，统一见 Workspace / Project 总览。

分页

大多数复用通用分页基类的列表接口支持以下查询参数：

参数	类型	默认值	说明
limit	integer	50	每页条数，最大 100
offset	integer	0	偏移量
sort_order	string	desc	排序方向，asc 或 desc
sort_by	string	因资源而异	排序字段，详见各资源文档

资源目录

资源	说明	文档
Sessions	会话管理、时间线、分支、分支重置与无冲突合并	Sessions
Temporary Conversations	不污染主叙事的临时对话高级资源，支持生命周期、导出与 SSE	Temporary Conversations
Chat	对话生成、SSE 流、Dry-run 与 runtime_trace 观察字段	Chat
Floors	楼层管理、分支操作	Floors
Pages	消息页管理、激活切换	Pages
Messages	消息管理、批量操作	Messages
Characters	角色卡管理、版本控制	Characters
Users	用户卡管理	Users
Variables	五级变量系统	Variables
Macros	宏展开规则、兼容边界，以及 dry-run / preview 能看到的结果	Macros
Prompt Runtime	查看 Prompt Runtime 总览、mode、policy、assets、inspection、capabilities 与 tool_transport 等观察字段	Prompt Runtime
Memories	记忆条目、边、后台任务与 scope 状态	Memories
Imports	SillyTavern 兼容导入	Imports
Exports	资源导出	Exports
Backup	核心资产备份导出、restore preview 与恢复入队	Backup
Backup Jobs	核心资产备份作业查询、控制与导出文件下载	Backup Jobs
Chat Transfer Jobs	异步聊天导入导出作业观测、控制与产物下载	Chat Transfer Jobs
Presets	预设管理、编辑器视图、条目级 CRUD	Presets
Worldbooks	世界书管理	Worldbooks
Regex Profiles	正则配置管理	Regex Profiles
LLM Profiles	LLM 配置管理、模型发现与测试	LLM Profiles
LLM Instances	LLM 实例配置	LLM Instances
Tools	查看工具目录、管理自定义工具、查询执行记录和会话权限	Tools
MCP Servers	连接外部 MCP 工具服务器并查看连接状态	MCP Servers
Accounts	账号管理	Accounts
Client Data	为应用或插件保存自己的结构化数据	Client Data
Session State	管理会话内受治理状态：注册、写入、读取和比较	Session State
Operation Logs	用户、LLM 和系统操作的审计日志	Operation Logs
Workspace / Project	工作区与项目路由族总览	Workspace / Project
Projects	Project 列表、会话、事件、SSE 订阅与成员管理	Projects
Agent Types	Workspace 级 Agent 类型	Agent Types
Project Agent Bindings	Project 级 Agent启用与手动触发	Project Agent Bindings
Project Agent Jobs	Project 级后台 Agent 作业看板	Project Agent Jobs
NodeGraph Runtime	Project 级图定义、版本、预览、后台运行与运行 trace	NodeGraph Runtime
Project Settings	Project 级 LLM、MCP、Tool Policy 覆盖	Project Settings
Effective Config	Project / Session 生效配置视图	Effective Config
Project Derived Outputs	Project 派生结果	Project Derived Outputs
Project Inbox	Project 收件箱与 owner 决策	Project Inbox
Clients	同一账号下的程序调用入口与 Client API Key	Clients
VC Tags	给 Floor 和资产版本保存命名引用	VC Tags

高级 API 资源

下面这些资源主要面向开发调试、运维排障、自动化脚本和平台集成，不属于普通聊天主流程接口。

第一次阅读这些页面时，建议先看每页开头的“什么时候需要看这页”“一个简单例子”“先理解几个词”。这样可以先知道它解决什么问题，再进入字段和错误码：

• Memory Jobs
• Chat Transfer Jobs
• Backup
• Backup Jobs
• Macros
• Prompt Runtime 总览
• Prompt Runtime Mode
• Prompt Runtime Policy
• Prompt Runtime Assets
• Prompt Runtime Inspection
• Prompt Runtime Capabilities
• Tools
• MCP Servers
• Client Data
• Session State
• Session-State Observation（内部）
• Operation Logs
• Workspace / Project 总览
• Projects
• Temporary Conversations
• Agent Types
• Project Agent Bindings
• Project Agent Jobs
• NodeGraph Runtime
• Project Settings
• Effective Config
• Project Derived Outputs
• Project Inbox
• Clients
• VC Tags

其中 Client Data 是一个独立的高级系统功能。它用于：

• 按 application 或 plugin 拥有者隔离存储客户端专属数据
• 为插件 owner 建立细粒度 grant 权限
• 提供治理动作审计日志
• 支持导入、导出、恢复、配额与并发控制

Session State 当前真实公开路由面由 /sessions/:sessionId/state/* 这组受治理公开接口，以及 turn API 中的 session_state_writes 共同组成。它们一起覆盖自定义命名空间注册、当前值写入、随回合一起提交的写入、删除、读取和比较。官方 SDK 会封装这组端点。内部观察面 /sessions/:sessionId/session-state/* 与 /floors/:floorId/session-state/* 仍保持内部定位，不进入官方包。

如果接入方只需要普通聊天能力，不需要优先接入这组资源。

官方集成层

如果需要在前端、桌面端或脚本中接入 TavernHeadless，建议优先使用官方集成层，而不是直接重复编写请求层和 SSE 处理逻辑。

当前官方集成层包含两个包：

• @tavern/sdk：负责 API 调用、默认请求头、统一错误和 SSE
• @tavern/client-helpers：负责 usage、timeline、流式状态、变量快照整理和错误展示映射

详细说明请参考：官方集成层