X Knowledge Agent

テーマ

REST API 仕様 ​

Next.js App Router で実装された REST API の仕様です。全エンドポイントに JWT 認証が必要です（認証系を除く）。

認証 ​

ログイン ​

http
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

レスポンス (200)

json
{
  "user": {
    "id": 1,
    "name": "User",
    "email": "user@example.com",
    "role": "admin"
  }
}

Set-Cookie ヘッダーで JWT トークンが付与されます。

ユーザー登録 ​

http
POST /api/auth/register
Content-Type: application/json

{
  "name": "New User",
  "email": "new@example.com",
  "password": "password123",
  "inviteCode": "abc123"
}

レスポンス (201)

json
{
  "user": {
    "id": 2,
    "name": "New User",
    "email": "new@example.com",
    "role": "member"
  }
}

ブックマーク ​

一覧取得 ​

http
GET /api/bookmarks?page=1&limit=20&category=ai-tools&source=chrome_cookie&sort=newest

クエリパラメータ

パラメータ型デフォルト説明
pagenumber1ページ番号
limitnumber20件数 (max: 100)
categorystring-カテゴリスラッグでフィルタ
sourcestring-取得元でフィルタ
sortstringnewestnewest, oldest, popular

レスポンス (200)

json
{
  "bookmarks": [
    {
      "id": 1,
      "tweetId": "1234567890",
      "text": "GPT-4 is now available...",
      "authorHandle": "openai",
      "authorName": "OpenAI",
      "tweetCreatedAt": "2025-01-15T10:00:00Z",
      "importedAt": "2025-01-16T08:00:00Z",
      "source": "chrome_cookie",
      "categories": [
        { "name": "AI-Tools", "slug": "ai-tools", "color": "#4caf50" }
      ],
      "media": [
        { "type": "photo", "url": "https://...", "thumbnailUrl": "https://..." }
      ]
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20
}

詳細取得 ​

http
GET /api/bookmarks/:id

レスポンス (200)

json
{
  "id": 1,
  "tweetId": "1234567890",
  "text": "GPT-4 is now available...",
  "authorHandle": "openai",
  "authorName": "OpenAI",
  "tweetCreatedAt": "2025-01-15T10:00:00Z",
  "importedAt": "2025-01-16T08:00:00Z",
  "source": "chrome_cookie",
  "rawJson": "...",
  "categories": [...],
  "media": [...],
  "knowledge": {
    "summary": "OpenAIがGPT-4の一般公開を発表",
    "action": "read_later",
    "tags": ["gpt4", "openai", "llm"],
    "sentiment": "positive",
    "confidence": 0.95,
    "relatedIds": [5, 12, 34],
    "analyzedAt": "2025-01-16T08:05:00Z",
    "ossReport": null
  }
}

検索 ​

AI セマンティック検索 ​

http
GET /api/search/ai?q=RAGの実装パターン&limit=10

クエリパラメータ

パラメータ型デフォルト説明
qstring(必須)検索クエリ（自然言語）
limitnumber10結果件数

レスポンス (200)

json
{
  "results": [
    {
      "bookmark": { "id": 5, "text": "...", "authorHandle": "..." },
      "relevance": 0.92,
      "reason": "RAGアーキテクチャの具体的な実装パターンを解説"
    }
  ],
  "query": "RAGの実装パターン"
}

AI分類パイプライン ​

パイプライン開始 ​

http
POST /api/categorize
Content-Type: application/json

{}

レスポンス (200)

json
{
  "jobId": "abc-123",
  "status": "started",
  "totalBookmarks": 42
}

進捗取得 (SSE) ​

http
GET /api/categorize
Accept: text/event-stream

イベントストリーム

data: {"stage": "entity_extraction", "progress": 10, "current": 4, "total": 42}

data: {"stage": "vision_analysis", "progress": 35, "current": 15, "total": 42}

data: {"stage": "semantic_tagging", "progress": 65, "current": 27, "total": 42}

data: {"stage": "categorization", "progress": 90, "current": 38, "total": 42}

data: {"stage": "complete", "progress": 100, "processed": 42, "errors": 0}

カテゴリ ​

一覧取得 ​

http
GET /api/categories

レスポンス (200)

json
{
  "categories": [
    {
      "id": 1,
      "name": "AI-Tools",
      "slug": "ai-tools",
      "color": "#4caf50",
      "description": "AI関連のツール・サービス",
      "bookmarkCount": 25
    }
  ]
}

統計 ​

ダッシュボード統計 ​

http
GET /api/stats

レスポンス (200)

json
{
  "totalBookmarks": 450,
  "categorizedBookmarks": 420,
  "uncategorizedBookmarks": 30,
  "totalCategories": 12,
  "totalMediaItems": 180,
  "recentImport": "2025-01-16T08:00:00Z",
  "topCategories": [
    { "name": "AI-Tools", "count": 85 },
    { "name": "DevOps", "count": 62 }
  ]
}

インポート ​

JSON インポート ​

http
POST /api/import
Content-Type: multipart/form-data

file: bookmarks.json

レスポンス (200)

json
{
  "imported": 150,
  "duplicates": 12,
  "errors": 0
}

設定 ​

CLI 認証状態 ​

http
GET /api/settings/cli-status

レスポンス (200)

json
{
  "authenticated": true,
  "method": "claude-cli-oauth",
  "model": "claude-sonnet-4-20250514"
}

API キーテスト ​

http
POST /api/settings/test
Content-Type: application/json

{
  "provider": "anthropic"
}

レスポンス (200)

json
{
  "valid": true,
  "provider": "anthropic",
  "method": "cli-oauth"
}

エラーレスポンス ​

すべてのエラーは以下の形式で返されます:

json
{
  "error": "エラーメッセージ",
  "code": "ERROR_CODE"
}

エラーコード ​

コードHTTP Status説明
UNAUTHORIZED401認証が必要
FORBIDDEN403権限不足
NOT_FOUND404リソースが見つからない
VALIDATION_ERROR400リクエストの検証エラー
RATE_LIMITED429レート制限超過
INTERNAL_ERROR500サーバー内部エラー