APIドキュメント

記事、検索などにアクセスするREST APIです。すべてのエンドポイントは次のパスで始まります: /api/v1.

認証

一部のエンドポイントではBearerトークン認証が必要です。トークンは Authorization ヘッダーに含めてください:

Authorization: Bearer YOUR_API_TOKEN

レート制限

匿名: 30 requests/minute
認証済み: 120 requests/minute

レスポンスヘッダーには次の値が含まれます: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

エンドポイント

GET /api/v1/articles

公開済み記事をフィルターとページネーション付きで取得します。未公開ステータスの記事には認証が必要です。

クエリパラメータ

パラメータ	型	説明
`page`	number	ページ番号（既定値: 1）
`limit`	number	1ページあたりの項目数（1-100、既定値: 12）
`status`	string	公開リクエストでは `published`; のみ使用できます。その他のステータスには認証が必要です
`category`	string	カテゴリーで絞り込み
`tag`	string	タグで絞り込み
`sortBy`	string	並び順: newest, oldest, views

GET /api/v1/articles/:id

IDで公開済み記事を1件取得します。未公開記事には認証が必要です。

POST /api/v1/articles 認証必須

新しい記事を作成します。APIトークン認証が必要です。

リクエスト本文（JSON）

{
  "title": "Article Title",
  "content": "<p>HTML content</p>",
  "summary": "Brief summary",
  "category": "ai",
  "status": "published",
  "tags": ["ai", "machine-learning"],
  "author": "Author Name",
  "source_url": "https://example.com",
  "thumbnail_url": "https://example.com/image.jpg"
}

POST /api/v1/articles/bulk 認証必須

複数の記事を1回のリクエストで作成します。記事オブジェクトの配列を送信してください。

GET /api/v1/search/suggest?q=query&lang=ko

検索オートコンプリート候補を取得します。FTS5ハイライト付きの記事タイトルを最大5件返します。任意のlang/localeフィルターは en, ko, または ja に対応し、1つの公開記事言語に候補を限定します。

GET POST /api/v1/articles/:id/reactions

GET: リアクション数とユーザーのリアクションを取得します。

POST: リアクションを切り替えます。 Types: like, fire, mindblown, heart.

POST /api/v1/curation-log 認証必須

キュレーションパイプラインの実行を記録します。自動キュレーションエージェントが使用します。

POST /api/v1/upload 認証必須

画像ファイルをアップロードします。 multipart/form-data 形式で送信し、 file フィールドを使ってください。

許可される形式: JPEG, PNG, WebP, GIF. 最大サイズ: 5MB. 返り値 { "url": "/uploads/..." }.

GET /api/v1/health

ヘルスチェックエンドポイントです。返り値: { "status": "ok" }.

フィードとディスカバリー

フィードエンドポイントは、対応箇所で次のクエリによるローカライズ記事フィードをサポートします: ?lang=en|ko|ja.

/openapi.json - 文書化済みAPIルート向けOpenAPI 3.x JSONスキーマ
/.well-known/openapi.json - 次へリダイレクトするwell-known OpenAPIエイリアス /openapi.json
/feed/rss.xml - RSS 2.0フィード
/feed/atom.xml - Atomフィード
/feed/category/:category.xml - カテゴリー別RSSフィード
/feed/tag/:tag.xml - タグ別RSSフィード
/feed.json - グローバルJSON Feed
/feed/category/:category.json - カテゴリー別JSON Feed
/feed/tag/:tag.json - タグ別JSON Feed
/jsonfeed.json and /feed/feed.json - 次へリダイレクトする一般的なJSON Feedエイリアス: /feed.json
/opensearch.xml - 公開検索ルート向けのOpenSearch説明文書