ObjectOS 暴露的 HTTP 表面 —— 由元数据生成、按权限作用域控制、由 OpenAPI 描述。

REST API

你声明的每个对象都会自动获得完整的 REST 端点集。每个 Action 都成为一个 POST。每个流程都成为对 /flows/... 的 POST。无需编写或部署单独的 API 层。

Base URL：https://<your-host>/api/v1。 OpenAPI spec 实时位于 /api/v1/openapi.json。

认证

ObjectOS 使用 Better Auth。/api/v1 下所有路由都需要已认证会话,除非显式标为公开（见公开表单）。认证方式在 apps/<app>/auth.config.ts 中配置 —— 通常是会话 cookie 或来自 /api/v1/auth/sign-in 的 bearer token。

权限按路由、按记录检查。下面标注了权限键（如 ai:chat）的路由会调用 requirePermission(...);记录级访问由数据引擎内的 RBAC + 行级安全 + 字段级安全强制。

发现

路径	方法	用途
`/api/v1`	GET	服务发现 —— 列出所有已注册路由、版本、作用域模式
`/api/v1/discovery`	GET	上述发现文档的显式别名
`/api/v1/openapi.json`	GET	运行时中每个端点的 OpenAPI 3.0 spec
`/api/v1/search`	GET	对所有对象上 searchable 字段的全文搜索

限制 API 暴露面

自动生成的端点按对象逐个治理,因此你无需编写任何路由代码就能将某个对象移出 API 或将其设为只读:

apiEnabled（boolean,默认 true）—— 设为 false 可将该对象完全从 REST 面移除。对其路由的请求返回 404。
apiMethods（可选白名单）—— 设置后,仅列出的操作可达;其他任何操作都在 REST 层被拒绝。允许的取值:get、list、create、update、delete、upsert、bulk、aggregate、history、search、restore、purge、import、export。

// 一个只读的参考对象,永远不可通过 API 写入:
defineObject({
  name: 'exchange_rate',
  apiMethods: ['get', 'list'],
  // ...fields
})

// 一个 API 永不暴露的内部对象:
defineObject({
  name: 'sync_cursor',
  apiEnabled: false,
  // ...fields
})

两者现在都在 REST 层强制执行（ADR-0049）—— 早期版本会解析这些属性但并不应用它们。

数据 —— `/api/v1/data/*`

对你声明的每个对象提供 CRUD + 高级查询。:object 是对象的 name（snake_case）。

路径	方法	用途
`/data/:object`	GET	列表/查询 —— 将 `where`、`orderBy`、`limit`、`offset`、`cursor`、`expand`、`select` 作为查询参数传入
`/data/:object/query`	POST	高级查询 —— 带 `groupBy` + `aggregations` 的完整 ObjectQL 请求体（见 ObjectQL）
`/data/:object/:id`	GET	获取单条记录。支持 `?select=` 和 `?expand=`
`/data/:object`	POST	创建。返回 `201` 与新记录
`/data/:object/:id`	PATCH	更新。传 `If-Match: <version>` header（或请求体中 `expectedVersion`）用于乐观并发 —— 冲突时返回 `409 CONCURRENT_UPDATE`
`/data/:object/:id`	DELETE	删除。同 `If-Match` 规则
`/data/:object/import`	POST	批量导入（CSV 或 JSON）。请求体：`{ format, csv? \| rows?, mapping?, dryRun? }`。每请求最多 5,000 行
`/data/:object/export`	POST	将记录导出为 `csv` / `xlsx` / `pdf` / `json`
`/data/:object/:id/shares`	GET / POST	单条记录共享 —— 列出/授予访问
`/data/:object/:id/shares/:shareId`	DELETE	撤销共享
`/data/lead/:id/convert`	POST	Salesforce 风格的 lead 转换（CRM 模板）。请求体：`{ accountId?, contactId?, createOpportunity? }`

快速示例

GET /api/v1/data/support_ticket?where={"status":{"$eq":"open"}}&orderBy=-created_at&limit=20
Authorization: Bearer <token>

{
  "items": [ { "id": "...", "subject": "...", "status": "open" } ],
  "total": 137,
  "nextCursor": "eyJpZCI6IjAxSDA..."
}

AI —— `/api/v1/ai/*`

AI Builder 和你的 Agent 所依赖的端点。

路径	方法	权限	用途
`/ai/models`	GET	`ai:chat`	列出已配置提供商的可用模型
`/ai/chat`	POST	`ai:chat`	单次聊天补全（同步）
`/ai/chat/stream`	POST	`ai:chat`	流式聊天（SSE）
`/ai/complete`	POST	`ai:chat`	原始补全端点
`/ai/conversations`	GET / POST	`ai:chat`	列出/创建持久化对话
`/ai/conversations/:id`	GET / DELETE	`ai:chat`	读取/删除对话
`/ai/conversations/:id/messages`	POST	`ai:chat`	追加用户消息并运行 Agent
`/ai/pending-actions`	GET	`ai:read`	HITL 审批队列 —— AI 提议的变更
`/ai/pending-actions/:id`	GET	`ai:read`	检查排队中的变更
`/ai/pending-actions/:id/approve`	POST	`ai:approve`	应用变更
`/ai/pending-actions/:id/reject`	POST	`ai:approve`	丢弃

ai:read 与 ai:approve 的拆分是让 AI Builder 对最终用户安全的关键安全原语。

Actions —— `/api/v1/actions/*`

你声明的每个 *.action.ts 都成为一个端点。

路径	方法	用途
`/actions/:action`	POST	调用 Action。请求体是 Action 的输入 schema。权限和输入校验来自 Action 声明

每个 Action 也作为 action_<name> 工具暴露给 AI —— 见 Actions。

流程 —— `/api/v1/flows/*`

路径	方法	用途
`/flows/:flow/start`	POST	启动一个流程。请求体是流程输入
`/flows/:flow/runs/:runId`	GET	运行中/已完成流程的状态 + 步骤输出
`/flows/:flow/runs/:runId/cancel`	POST	取消进行中的运行

元数据 —— `/api/v1/meta/*`

对运行时元数据的只读自省。供工具和 Console 使用。

路径	方法	用途
`/meta`	GET	所有元数据类型（`object`、`view`、`action`、`flow`、`agent`……）
`/meta/:type`	GET	列出某类型项目。`?package=<id>` 过滤
`/meta/:type/:name`	GET	获取单项。`?layers=true` 返回 3 态 diff 视图（base / package / overlay）
`/meta/:type/:name/references`	GET	查找引用此项的所有元数据项
`/meta/:type/:name/history`	GET	该项的审计轨迹
`/meta/:type/:section/:name`	GET / POST	读取/upsert 分段的元数据项
`/meta/:type/:section/:name`	DELETE	删除分段项

共享与审批

路径	方法	用途
`/sharing/rules`	GET / POST / DELETE	管理共享规则
`/sharing/rules/:idOrName/evaluate`	POST	针对上下文 dry-run 一条规则
`/approvals/processes`	GET / POST	审批流程定义
`/approvals/requests`	GET / POST	提交/列出审批请求
`/approvals/requests/:id/approve`	POST	决策：批准
`/approvals/requests/:id/reject`	POST	决策：拒绝

报表与搜索

路径	方法	用途
`/reports`	GET / POST / PATCH	报表 CRUD
`/reports/:id/run`	POST	执行报表 —— 返回聚合行
`/reports/:id/schedule`	POST	调度定期投递

公开表单

仅有的未认证路由,通过 FormView.sharing.allowAnonymous 显式启用。

路径	方法	认证
`/forms/:slug`	GET	公开 —— 返回表单 schema
`/forms/:slug/submit`	POST	公开 —— 提交响应

工具

路径	方法	权限	用途
`/email/send`	POST	`email:send`	通过已配置提供商发送邮件

错误信封

每个非 2xx 响应遵循相同形状：

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Missing ai:approve on conversation 01H…",
    "details": { "permission": "ai:approve", "subject": "01H…" }
  }
}

常见 code：UNAUTHENTICATED、PERMISSION_DENIED、VALIDATION_ERROR、NOT_FOUND、CONCURRENT_UPDATE、RATE_LIMITED、INTERNAL。

版本管理

/api/v1 是稳定 API。破坏性变更进入 /api/v2,两者在一个小版本期内并行服务。当前版本和弃用周期见 GET /api/v1。

参见

ObjectQL —— /data/* 使用的查询语言
字段类型 —— 数据可以呈现的形状
Build → Actions —— 声明自定义端点
安全 —— 每个路由运行前检查什么

REST API

On this page