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-100, 기본값: 12)
`status`	string	공개 요청에서는 `published`; 만 사용할 수 있으며, 다른 상태는 인증이 필요합니다
`category`	string	카테고리로 필터링
`tag`	string	태그로 필터링
`sortBy`	string	정렬: newest, oldest, views

GET /api/v1/articles/:id

ID로 공개 기사를 하나 조회합니다. 공개되지 않은 기사는 인증이 필요합니다.

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 인증 필요

여러 기사를 한 번에 만듭니다. 기사 객체 배열을 보내세요.

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

검색 자동완성 제안을 가져옵니다. FTS5 하이라이트가 적용된 기사 제목을 최대 5개 반환합니다. 선택적 lang/locale 필터는 en, ko, 또는 ja 를 지원하며 한 언어의 공개 기사로 제안을 제한합니다.

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 설명 문서