API Reference · 공지사항

공지사항 목록 조회

콘텐츠에 노출할 공지 목록을 조회합니다. 모든 콘텐츠에 공통으로 노출되는 공통 공지와 해당 콘텐츠 전용 공지가 함께 반환됩니다. 목록은 요약만 반환하므로, 본문(body)은 상세 조회로 가져옵니다.

GET/api/v1/contents/{content_id}/notices

요청 파라미터

content_id (path, uuid, required) — 공지를 조회할 콘텐츠 ID.
limit (query, int, default 50, max 200) — 한 페이지에 반환할 항목 수.
offset (query, int, default 0) — 건너뛸 항목 수.

현재 게시 중인 공지만 반환합니다. 게시 상태가 아니거나 게시기간 (starts_at · ends_at) 을 벗어난 공지는 제외됩니다.

요청예시

shell

curl -H "Authorization: Bearer sk_pub_prod_4eC39HqLyjWDarjtT1zdp7dc" \
     "https://added.blomics.net/api/v1/contents/0193a1b2-3c4d-5e6f-7890-abcdef012345/notices?limit=50&offset=0"

응답 필드

200 OK — items 배열과 total 총 개수를 반환합니다. 정렬은 상단 고정 (is_pinned) → 정렬 순서 → 최신 게시순입니다.

items (array) — 공지 요약 객체 배열.
- notice_id (uuid) — 공지 식별자.
- scope (string) — common(공통 공지) / content(콘텐츠 전용).
- category (string) — general / event / maintenance / update.
- title (string) — 공지 제목.
- is_pinned (boolean) — 상단 고정 여부.
- starts_at (ISO 8601, nullable) — 게시 시작 시각. null 이면 즉시 게시.
- ends_at (ISO 8601, nullable) — 게시 종료 시각. null 이면 무기한.
- published_at (ISO 8601, nullable) — 게시 시각.
total (int) — 조건에 매치되는 전체 개수.

본문(body) 은 목록 응답에 포함되지 않습니다. 본문이 필요하면 /api/v1/contents/{content_id}/notices/{notice_id} 상세 조회를 사용하세요.

응답예시

json

{
  "items": [
    {
      "notice_id": "0193c1d2-3e4f-5a6b-7c8d-9e0f12345678",
      "scope": "common",
      "category": "maintenance",
      "title": "정기 점검 안내",
      "is_pinned": true,
      "starts_at": "2026-06-01T00:00:00.000Z",
      "ends_at": "2026-06-02T00:00:00.000Z",
      "published_at": "2026-05-31T09:00:00.000Z"
    },
    {
      "notice_id": "0193c1d2-3e4f-5a6b-7c8d-9e0fabcdef01",
      "scope": "content",
      "category": "event",
      "title": "신규 이벤트 오픈",
      "is_pinned": false,
      "starts_at": null,
      "ends_at": null,
      "published_at": "2026-05-28T12:00:00.000Z"
    }
  ],
  "total": 2
}

에러처리

400 INVALID_PARAM — limit / offset 형식 오류.
401 UNAUTHORIZED — 인증 실패.
404 NOT_FOUND — 콘텐츠 없음 또는 소유권 위반(404 은닉).
500 INTERNAL_ERROR — 서버 오류.