SIRT REST API クイックスタート

SIRT.aiが提供するREST API(HTTP)の使い方をまとめたクイックスタートガイドです。MCP接続ではなく、直接HTTP(REST)でSIRTを呼び出したい方(自作スクリプト、他言語クライアント、サーバー間連携など)向けの内容です。

1. 認証と基本形

全エンドポイントは https://app.sirtai.org/api/v1 配下にマウントされています。

認証はAPIキーによるBearer認証です。Authorization: Bearer <YOUR_API_KEY> ヘッダ、または X-API-Key: <YOUR_API_KEY> ヘッダのどちらでも受け付けます。キーが無ければ 401 Missing API key、無効・revoke済みなら 401 Invalid or revoked API key を返します。

基本形(検索の例):

curl -sS "https://app.sirtai.org/api/v1/search?q=roadmap&top_k=5" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

書き込み系はJSON POSTです:

curl -sS -X POST "https://app.sirtai.org/api/v1/crystallize" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"raw_context": "今日決めたこと: ...", "project": "my-project"}'

全ルートは同一の認証・レート制限ミドルウェアを通ります。

2. 主要エンドポイント(用途別)

2.1 ノード保存(2ステップ: crystallize → confirm)

SIRTの「保存」は2段階です。まず raw_context(自由文)をノード案(draft)に分解し、それをレビューしてから確定(実際に保存)します。

`POST /crystallize` — 自由文をノード案に分解する(まだ保存されない)。必須フィールドは raw_context(string, 1文字以上)と project(string, 1文字以上)。

curl -sS -X POST "https://app.sirtai.org/api/v1/crystallize" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"raw_context": "...", "project": "my-project", "mode": "auto"}'

`POST /crystallize/confirm` — 上記の応答に含まれる node_drafts / assertion_drafts をそのまま渡すと実際にノードが作成されます。node_drafts の各要素には draft_id / classification / node_type / summary(240字以内) / body(12,000字以内) / tier1_labels / trust_score / confidence などが必須です。

curl -sS -X POST "https://app.sirtai.org/api/v1/crystallize/confirm" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"node_drafts": [ /* /crystallize の応答から丸ごと転記 */ ], "assertion_drafts": []}'

2.2 ノード検索

`GET /search?q=<query>&top_k=<n>` — 全文検索(FTS5)。q は必須。3文字未満の場合は自動的にLIKE部分一致にフォールバックし、応答に fallback_reason が付きます。

`GET /search/hybrid?q=<query>&top_k=<n>&source_url=&node_type=&source_label=` — 全文検索とベクトル検索のハイブリッド(RRF)。任意フィルタはベクトル側にのみ適用されます。

curl -sS "https://app.sirtai.org/api/v1/search/hybrid?q=onboarding&top_k=10" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

2.3 ノード取得

`GET /nodes/:id` — 単一ノード取得。存在しなければ 404 Node not found。

`POST /nodes/batch-get` — 複数ノードをID配列でまとめて取得。body は {"ids": ["node_xxx", ...]}。

curl -sS -X POST "https://app.sirtai.org/api/v1/nodes/batch-get" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["node_abc123", "node_def456"]}'

2.4 キー管理(self-service, list/issue/revoke/rotate)

自分のテナントが持つAPIキーは、そのテナントの有効なキーがあれば自己管理できます。

`GET /keys` — 自テナントのキー一覧(key_hash は含まれません)。

`POST /keys` — 新規キー発行。body は {"label"?: string, "profile"?: "full"|"role_agent"}。平文キー(api_key)はこのレスポンスに一度だけ含まれます。profile を省略すると発行元キーと同じprofileを継承します。発行元より高いprofileを要求すると 403。role_agent profileはテナント側の許可が有効な場合のみ発行可能です。アクティブキー上限に達していると 409 を返します。

curl -sS -X POST "https://app.sirtai.org/api/v1/keys" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-pipeline"}'

`POST /keys/:key_id/revoke` — 指定キーをrevoke。テナントの最後の1本を直接revokeしようとすると 409(自己ロックアウト防止)。存在しない、または他テナントのキーは 404。

`POST /keys/:key_id/rotate` — 新キー発行と旧キーrevokeを1回のバッチでアトミックに実行します(平文キーの再取得はできません — rotationのみ)。新キーの平文はこのレスポンスに一度だけ含まれます。

2.5 その他: 外部書き込み連携(pull型コネクタAPI)

クライアント側コネクタ(サーバー側から能動的にpush接続できないクライアント)が、SIRTに溜まった「書き出し待ち」の外部連携をpullして完了報告するためのAPIです。

`GET /external-writes/pending?target=&limit=` — 未処理の外部書き込みタスク一覧。target は obsidian / notion / gdrive / github 等の値。limit は最大200。

`POST /external-writes/complete` — 完了報告。body は {"node_id": "node_...", "target": "...", "status": "written"|"skipped"|"failed", "destination"?: string, "error"?: string}。対象タスクが存在しなければ 404。

3. 利用回数

SIRTはプランによるAPI call数、node作成数、保存・インポート回数、Server AI処理回数の上限を設けません。

プラン	calls/day
`free`	無制限
`pro`	無制限
`max`	無制限

4. エラー応答の読み方

全ルートで共通して、エラーは {"error": "<message>"} というJSONボディで返ります。代表的なステータスコード:

ステータス	意味	例
`400`	不正なリクエスト(JSON構文エラー、バリデーション失敗など)	`{"error": "Invalid JSON"}`
`401`	APIキー欠落、または無効・revoke済み	`{"error": "Missing API key"}` / `{"error": "Invalid or revoked API key"}`
`403`	プロファイル昇格の試み、role_agent発行が未許可	`{"error": "a role_agent-profile key cannot issue a full-profile key"}`
`404`	対象が存在しない、または自テナントに属さない	`{"error": "Node not found"}` / `{"error": "No active key with that id for this tenant"}`
`409`	競合(最後の1本のキーをrevoke、アクティブキー上限到達など)	`{"error": "Refusing to revoke the tenant's last active key — use rotation instead"}`
`500`	サーバー側エラー	`{"error": "Snapshot build failed"}`

/crystallize や /crystallize/confirm のようにスキーマで入力検証しているルートでは、400 のメッセージがバリデーションエラー文字列(フィールドパス付き)になることがあります。