REST API

ObjectOS 暴露的 HTTP 表面 —— 由後設資料生成、按許可權作用域控制、由 OpenAPI 描述。

你宣告的每個物件都會自動獲得完整的 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