API ドキュメント

Bookmark Hub 公開 API の仕様と使い方

認証

設定画面で生成した API キーを Authorization ヘッダーに設定してください。キーは生成時に一度だけ表示されます。

Authorization: Bearer bh_xxxxxxxxxxxxx

ブックマーク

POST/api/bookmarks

ブックマークを作成する

Request

{
  "url": "https://example.com/article",
  "title": "記事タイトル（任意）",
  "description": "メモ（任意）",
  "source": "api"
}

Response

{
  "id": "uuid",
  "url": "https://example.com/article",
  "status": "pending",
  "source": "api"
}

GET/api/bookmarks

ブックマーク一覧を取得する

クエリパラメータ

名前	型	デフォルト
`page`	number	1
`limit`	number	20（最大100）
`status`	string	—
`source`	string	—

Response

{
  "data": [
    "{ id, url, title, status, ... }"
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

GET/api/bookmarks/:id

ブックマークの詳細を取得する

Response

{
  "id": "uuid",
  "url": "https://example.com",
  "title": "タイトル",
  "summary": "AI による要約",
  "status": "processed",
  "tags": [
    {
      "name": "技術"
    }
  ]
}

PATCH/api/bookmarks/:id

ブックマークを更新する

Request

{
  "title": "新しいタイトル（任意）",
  "description": "新しいメモ（任意）"
}

DELETE/api/bookmarks/:id

ブックマークを削除する

Response

{
  "deleted": true
}

検索

POST/api/search

セマンティック検索を実行する

Request

{
  "query": "TypeScript の型安全なパターン",
  "limit": 10,
  "filters": {
    "source": "slack",
    "status": "processed"
  }
}

Response

{
  "results": [
    {
      "id": "uuid",
      "url": "https://example.com",
      "title": "タイトル",
      "summary": "要約",
      "similarity": 0.87
    }
  ]
}

エラーレスポンス

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

{ "error": "エラーメッセージ" }

ステータス	意味
`400`	リクエスト不正
`401`	認証エラー（API キーが無効）
`403`	権限不足（プラン制限・チーム未所属など）
`404`	リソースが見つからない
`409`	競合（URL 重複など）
`500`	サーバーエラー

レート制限

API キーごとに 1 分間あたり 60 リクエストまで。制限を超えた場合はステータス 429 が返されます。