API docs by Redocly

engine-api (0.1.0)

Download OpenAPI specification:

비즈크러시 소비자용 발행 기사 API. 인증은 x-api-key 헤더(published 키 — 발급은 운영 채널로 문의).

이 문서는 커밋된 스펙에서 자동 생성·게시된다 — 사본을 따로 보관하지 말고 이 URL을 참조한다.

Health

기동 확인. ⛔ DB·GCS를 건드리지 않는다 — 의존이 잠깐 흔들릴 때 Cloud Run이 컨테이너를 죽이면 복구가 더 늦어진다. 「프로세스가 살아 있나」만 답한다.

Responses

Response samples

Content type
application/json
{ }

List Published

재구성·검수를 거쳐 발행된 기사 목록(커서 페이지네이션).

⚠️ publisher·source_url·ai_notice 3필드가 응답에 반드시 포함된다 — 출처 표기·AI 고지는 게재 시 필수 렌더 대상이다. ⚠️ 고지는 2필드다(ai_notice + source_notice) — 매체명·링크는 별 필드로 렌더한다. 원문 메타 3필드(source_published_at·subtitle·section)도 함께 실린다. ⚠️ 커서는 published_at 기준이다(수정 시각 아님) — 정정·재발행이 있어도 같은 기사가 새 기사로 보이지 않는다.

Authorizations:
publishedKey
query Parameters
Updated Since (string) or Updated Since (null) (Updated Since)

이 발행 시각 이후 — 오프셋 필수(예: 2026-08-18T00:00:00Z)

after_id
integer (After Id) >= 0
Default: 0

같은 시각 내 이 id 이후

limit
integer (Limit) [ 1 .. 500 ]
Default: 100
include_body
boolean (Include Body)
Default: true

false면 body_md·refs가 null(홈 목록용 경량 응답). ⚠️ 기본값은 전문 포함.

lang
string (Lang)
Default: "ko"

응답에 실을 기사의 언어. 허용값: ko, en (기본 ko). ⚠️ 미지정은 「전 언어」가 아니라 ko만입니다 — 전량 적재 커서가 다른 언어로 오염되지 않게 한 기본값입니다. 허용값 밖은 빈 목록이 아니라 400을 돌려줍니다.

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next": {
    }
}

List Latest

최신 발행 기사 — 홈 히어로·최신 탭용. 발행 시각 내림차순(최신부터).

접근 방식 2종을 받친다 — 페이지 번호 UI: offset=(페이지-1)×limit으로 점프하고 응답 total로 페이지 수를 계산한다(ceil(total/limit) — 발행이 늘면 페이지가 자동으로 는다) · 더보기/스크롤: 응답 next(published_before·before_id)를 그대로 되던진다 — null이면 끝. ⛔ 둘을 한 요청에 섞으면 400. ⛔ 전량 적재(동기화)에는 쓰지 않는다 — 걷는 도중 발행된 새 기사는 이 walk에 안 잡힌다(화면은 새로고침이 그 몫). 하나도 빠짐없이 받는 축은 GET /v1/published 오름차순 커서다. ⚠️ 히어로(Hot Topic)는 서버가 고르지 않는다 — items[0]이 그 자리다(편집 선정 아님). ⚠️ 본문은 기본으로 실리지 않는다(include_body=false) — GET /v1/published의 기본값과 다르다.

Authorizations:
publishedKey
query Parameters
limit
integer (Limit) [ 1 .. 50 ]
Default: 10

페이지 크기 — 홈 카드는 한 화면분, 최신 탭은 next로 이어 받는다

Published Before (string) or Published Before (null) (Published Before)

이 발행 시각 이전(더 과거) 페이지 — 응답 next.published_before를 그대로 되던진다. 오프셋 필수(예: 2026-09-01T10:00:00Z)

before_id
integer (Before Id) >= 0
Default: 0

같은 발행 시각 동률 경계 — 응답 next.before_id를 그대로 되던진다

offset
integer (Offset) [ 0 .. 10000 ]
Default: 0

페이지 번호 UI용 점프 — offset = (페이지-1) × limit. 페이지 수는 응답 total로 계산한다(ceil(total/limit)). ⛔ 커서(published_before)와 한 요청에 섞으면 400

include_body
boolean (Include Body)
Default: false

true면 body_md·refs를 동봉한다(기본 false — 홈 카드는 전문이 필요 없다). 🔴 브리핑 카드(digest가 null이 아닌 기사)를 그리려면 true가 필요하다.

lang
string (Lang)
Default: "ko"

응답에 실을 기사의 언어. 허용값: ko, en (기본 ko). ⚠️ 미지정은 「전 언어」가 아니라 ko만입니다 — 전량 적재 커서가 다른 언어로 오염되지 않게 한 기본값입니다. 허용값 밖은 빈 목록이 아니라 400을 돌려줍니다.

header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next": {
    },
  • "total": 0
}

Get Published

발행 기사 단건 — 상세 화면 직접 진입용.

⚠️ 발행 중이 아닌 slug는 404다(410 아님 — 내린 기사의 존재를 API가 증언하지 않는다). 고지 조립 규칙은 목록과 동일하다 — 같은 기사가 목록과 단건에서 다른 고지를 들고 나오지 않는다.

Authorizations:
publishedKey
path Parameters
slug
required
string (Slug)
header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response samples

Content type
application/json
{
  • "ai_notice": "string",
  • "alternates": [
    ],
  • "body_md": "string",
  • "digest": { },
  • "id": 0,
  • "images": [
    ],
  • "lang": "string",
  • "market": "string",
  • "perspective_notice": "string",
  • "published_at": "2019-08-24T14:15:22Z",
  • "publisher": "string",
  • "refs": [
    ],
  • "section": { },
  • "slug": "string",
  • "source_notice": "string",
  • "source_published_at": "2019-08-24T14:15:22Z",
  • "source_url": "string",
  • "subtitle": "string",
  • "summary": "string",
  • "summary_points": [
    ],
  • "tags": [
    ],
  • "title": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "view_count": 0,
  • "writer_mode": "string"
}

Record Published View

조회 이벤트 접수 — 같은 조회자의 같은 기사는 KST 하루 1회만 집계.

⚠️ 브라우저 직접 호출은 body 생략(IP+UA 해시로 집계) · BFF 경유는 viewer_key 필수(없으면 전 사용자가 조회자 1명으로 접힌다 — ViewIn 참조). ⚠️ navigator.sendBeacon은 x-api-key 헤더를 못 실으므로 fetch(url, {method: "POST", keepalive: true, headers: {"x-api-key": …}})로 보낸다. 조회수는 표시용 신호이지 증빙이 아니다.

Authorizations:
publishedKey
path Parameters
slug
required
string (Slug)
header Parameters
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
Any of
Viewer Key (string) or Viewer Key (null) (Viewer Key)

호출자가 유지하는 조회자 식별자(쿠키 해시 등). 🔴 BFF(서버) 경유 호출은 필수다 — 서버 뒤에서는 X-Forwarded-For 신뢰 축이 BFF의 IP로 접혀 전 사용자가 조회자 1명이 된다. 브라우저 직접 호출은 생략(IP+UA 해시로 대체). 저장은 sha256 해시뿐 — 원값은 남지 않는다

Responses

Request samples

Content type
application/json
Example
{
  • "viewer_key": "stringst"
}

Response samples

Content type
application/json
{
  • "counted": true
}