REST API

宣言したすべてのオブジェクトに、完全な REST エンドポイントセットが自動的に付与されます。 すべてのアクションは POST になります。すべてのフローは /flows/... への POST になります。記述やデプロイが必要な独立した API レイヤーは存在しません。

ベース URL: https://<your-host>/api/v1。 OpenAPI 仕様は /api/v1/openapi.json で公開されています。

Authentication

ObjectOS は Better Auth を使用します。 /api/v1 配下のすべてのルートは、明示的に public とマークされていない限り、 認証済みセッションを必要とします（Public forms を参照）。認証方式は apps/<app>/auth.config.ts で設定します。通常はセッション Cookie か、 /api/v1/auth/sign-in から取得したベアラートークンです。

権限は ルートごと、レコードごと にチェックされます。以下で権限キー （例: ai:chat）が付記されているルートは requirePermission(...) を呼び出します。レコードレベルのアクセスは、データエンジン内部の RBAC + 行レベルセキュリティ + フィールドレベルセキュリティによって強制されます。

Discovery

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）— 以前のバージョンではこれらの プロパティをパースするだけで、適用していませんでした。

Data — /api/v1/data/*

宣言したすべてのオブジェクトに対する CRUD + 高度なクエリ。:object は オブジェクトの name（snake_case）です。

Quick example

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 と エージェント が動作するためのエンドポイントです。

ai:read と ai:approve の分離は、AI Builder をエンドユーザーにとって安全なものにする セキュリティプリミティブです。

Actions — /api/v1/actions/*

宣言したすべての *.action.ts がエンドポイントになります。

各アクションは action_<name> ツールとして AI にも公開されます — Actions を参照してください。

Flows — /api/v1/flows/*

Metadata — /api/v1/meta/*

実行中のランタイムのメタデータへの読み取り専用のイントロスペクション。 ツールや Console に役立ちます。

Sharing & approvals

Reports & search

Public forms

FormView.sharing.allowAnonymous でオプトインする、唯一の 認証なし のルートです。

Utilities

Error envelope

すべての非 2xx 応答は同じ形式に従います:

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

一般的なコード: UNAUTHENTICATED、PERMISSION_DENIED、 VALIDATION_ERROR、NOT_FOUND、CONCURRENT_UPDATE、 RATE_LIMITED、INTERNAL。

Versioning

/api/v1 は 安定版 API です。破壊的変更は /api/v2 に入り、 両方が 1 つのマイナーリリースの間並行して提供されます。現在のバージョンと 非推奨化の予定は GET /api/v1 にあります。

See also

• ObjectQL — /data/* で使用されるクエリ言語
• Field types — データが取り得る形状
• Build → Actions — カスタムエンドポイントを宣言
• Security — すべてのルートが実行前にチェックする内容