開発者向け：REST API（/api/v1）の使い方
開発者向け：REST API（/api/v1）の使い方
iknow.dev は REST API（/api/v1）と MCP の両方でデータにアクセスできます。ブラウザの Vue アプリも同じ API を使っています。このページは プログラムから iknow.dev を操作したい開発者 向けの入口です。
詳細な全エンドポイント一覧はリポジトリ内
docs/api-specification.md（公式 API 仕様書）を参照してください。ここでは 認証の仕組み・主要カテゴリ・MCP との使い分け をまとめます。
ベース URL
https://{your-domain}/api/v1/...
認証方式
| 方式 | 用途 | 概要 |
|---|---|---|
| Cookie セッション | ブラウザ SPA（Vue） | auth:experts ガード。ログイン後の Cookie で認証 |
| OAuth Bearer トークン | MCP / 外部連携 | Authorization: Bearer <token>。Passport 発行 |
| なし（匿名） | 公開読取・匿名チャット | パブリックエージェントの GET、iknow Navigator 限定 POST |
CSRF（Cookie 利用時）
POST / PUT / DELETE には CSRF トークンが必要です。
GET /csrf-tokenでトークン取得X-CSRF-TOKENヘッダーまたは_tokenボディで送信
ブラウザから直接 curl するより、MCP 連携（OAuth Bearer）の方が手軽なことが多いです。
主要エンドポイントカテゴリ
| カテゴリ | 例 | アクセス |
|---|---|---|
| Expert（自分） | GET/PUT/DELETE /api/v1/expert |
認証済み |
| エージェント | GET/POST/PUT/DELETE /api/v1/agents/... |
オーナー・メンバー / オーナーのみ |
| ナレッジ | GET/POST/PUT/DELETE /api/v1/knowledge/... |
公開範囲に応じた認可 |
| チャット | GET/POST /api/v1/chats/...、/messages |
エージェント権限に準拠 |
| インポート | POST /api/v1/knowledge/import-file 等 |
オーナー |
| 利用分析 | GET /api/v1/analytics/referrals、/message-reports、/message-feedbacks、/knowledge-citations、/knowledge-review、/review-summary |
自分がオーナーのエージェント分のみ |
| 添付 | POST/GET /api/v1/knowledge/attachments/... |
編集権 / 閲覧権 |
| 匿名チャット | POST /api/v1/public/agents/{code}/chats |
iknow Navigator 限定 |
| OAuth ログイン | GET /api/v1/{provider}/auth/redirect |
誰でも。SaaS は qiita / github / google のみ。microsoft はオンプレで有効化した場合のみ（インポート連携専用・ログイン不可） |
MCP との使い分け
| やりたいこと | おすすめ |
|---|---|
| Cursor / Claude からナレッジ検索・編集 | MCP（/mcp）— ツールが整備済み |
| 自社システムとのバッチ連携 | REST API — エンドポイントを直接呼ぶ |
| ブラウザ UI と同じ操作 | REST API（Cookie）— Vue と同じ |
| 複数エージェント横断 | MCP オーケストレーション（/mcp + agent_code） |
| 匿名でパブリック読取 | MCP Public（/mcp/public/{agentCode}） |
→ 「Cursor / Claude から使う（MCP 連携）」「どこから使う？ — Web・MCP・Teams の選び方」
OAuth トークンの取得（MCP 用）
- アカウント設定 → 「Cursorへインストール」 等で OAuth クライアント発行
GET /oauth/authorize→ ユーザー認可 →POST /oauth/tokenで Bearer 取得- スコープ:
mcp:use
レスポンスの URL 解決
API レスポンスの avatar_url や画像 URL は、環境変数 VITE_BUILD_CDN_URL / STATIC_ASSET_CDN_URL により ルート相対 または CDN 絶対 URL になります。
例外: ナレッジ添付（/api/v1/knowledge/attachments/...）は常に Laravel 経由で認可チェック付き配信（CDN 非経由）。
レート制限
チャット送信・ナレッジ書き込み・LLM 編集・インポート・Teams・MCP などの書き込み系・LLM 呼び出し系には throttle:* ミドルウェア によるレート制限が設定されています。上限に達すると HTTP 429 が返ります。各上限の既定値と環境変数は docs/api-specification.md §1.6 を参照してください。
主なリミッター（抜粋）:
| 対象 | 既定上限 | キー |
|---|---|---|
| チャット送信（LLM） | 20/分 + 100/時 + 300/日 | Expert ID |
| ナレッジ書き込み | 60/分 | Expert ID |
| LLM 編集（AI修正） | 10/分 + 300/日 | Expert ID |
| Teams Bot 受信 | 20/分 | エージェントコード |
| MCP 意味検索・JSON集計 | 認証済み 30/分 / 匿名 10/分 | user ID / IP |
MCP の
search-knowledge（keyword モード）・get-knowledge・list-knowledgeなどコスト低い読取系はレート制限なし。
エラーの読み方
| コード | 意味 |
|---|---|
| 401 | 未認証。ログインまたはトークン再取得 |
| 403 | 権限不足（オーナー専用操作等） |
| 404 | 存在しない、またはプライベートで非メンバー |
| 422 | バリデーションエラー（文字数超過・形式不正等） |
| 429 | レート制限超過。しばらく待ってから再送 |
→ 「アクセス拒否・リダイレクトの意味と対処一覧」「利用上限・クォータ早見表」