API Documentation

RESTful API for accessing articles, search, and more. All endpoints are prefixed with /api/v1.

Authentication

Some endpoints require authentication via Bearer token. Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Rate Limiting

Anonymous: 30 requests/minute
Authenticated: 120 requests/minute

Response headers include: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

GET /api/v1/articles

List published articles with filtering and pagination. Unpublished statuses require authentication.

Query Parameters

Param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (1-100, default: 12)
`status`	string	Public requests may only use `published`; other statuses require auth
`category`	string	Filter by category
`tag`	string	Filter by tag
`sortBy`	string	Sort: newest, oldest, views

GET /api/v1/articles/:id

Get a single published article by ID. Non-published articles require authentication.

POST /api/v1/articles Auth Required

Create a new article. Requires API token authentication.

Request Body (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 Auth Required

Create multiple articles in a single request. Send an array of article objects.

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

Get search autocomplete suggestions. Returns up to 5 matching article titles with FTS5 highlighting. Optional lang/locale filter supports en, ko, or ja to restrict suggestions to one published article language.

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

GET: Get reaction counts and user reactions.

POST: Toggle a reaction. Types: like, fire, mindblown, heart.

POST /api/v1/curation-log Auth Required

Log a curation pipeline run. Used by automated curation agents.

POST /api/v1/upload Auth Required

Upload an image file. Send as multipart/form-data with a file field.

Allowed types: JPEG, PNG, WebP, GIF. Max size: 5MB. Returns { "url": "/uploads/..." }.

GET /api/v1/health

Health check endpoint. Returns { "status": "ok" }.

RSS/Atom Feeds

/feed/rss.xml - RSS 2.0 feed
/feed/atom.xml - Atom feed
/feed/category/:category.xml - Category-specific feed
/feed/tag/:tag.xml - Tag-specific feed