Delivery API

Atlas에서 게시된 페이지, 항목, 글로벌, 경로, 리디렉션을 읽고 웹사이트의 빌드를 보고합니다.

이 페이지는 영어에서 번역되었습니다. 내용이 다를 경우 영어 버전이 우선합니다. 영어로 읽기

Delivery API는 웹사이트가 게시된 콘텐츠를 읽는 방법입니다. 서버 코드에서만 호출하세요.

기본 URL과 인증

https://<delivery host>/v1/delivery/environments/{environmentId}
Authorization: PublishedConsumer <delivery token>

각 토큰은 하나의 환경에 속합니다. 개발과 프로덕션은 토큰이 따로 있습니다.
토큰은 무작위 43자이며, 한 번만 표시되고, 1일에서 365일 동안 유효하며, Studio에서 언제든 취소할 수 있습니다. Atlas는 지문만 저장합니다.
프로덕션 토큰은 해당 환경의 라이브 릴리스만 읽습니다.

캐싱

게시된 응답에는 다음이 포함됩니다.

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300
ETag: W/"…"
X-Atlas-Content-Version: …
Vary: Authorization, Accept-Encoding

마지막 ETag와 함께 If-None-Match를 보내세요. 변경된 것이 없으면 Atlas는 304 Not Modified로 응답합니다. 이를 웹훅과 함께 사용하면 게시 시점에 새로 고칠 수 있습니다. 미리보기와 배포 응답은 private, no-store입니다.

엔드포인트

`GET /site`

환경, 라이브 릴리스(프로덕션), 콘텐츠 버전, 활성 계약의 다이제스트와 버전입니다.

`GET /routes`

사이트맵과 정적 생성을 위한 게시된 모든 경로입니다. route, pageType, entryId, title, lastModified, noindex, locales. 최대 5,000개 경로.

`GET /pages?route=/about&locale=en`

게시된 페이지 하나입니다.

필드	내용
`page`	`id`, `route`, `title`, `pageType`, `publishedAt`, `entryId`
`document`	`pageType`, `pageFields`, `regions`: 각 리전은 순서가 있는 섹션 목록입니다
`document.regions[key][n]`	`id`, `component { id, version }`, `props`, `hidden`
`entry`	페이지 유형에 연결된 항목이 있으면 페이지에 바인딩된 항목
`seo`	`title`, `description`, `noindex`, `structuredDataType`, `canonicalPath`, `faq`
`head`	바로 출력할 수 있는 `title`, `meta[]`, `links[]`, `jsonLd[]`. 또는 `headProblem`과 함께 `null`
`assets`	페이지가 사용하는 모든 이미지(에셋 ID 기준): `url`, `renditions`, `alt`, `focalPoint`
`locale`, `direction`, `translation`, `alternates`	응답 언어, `ltr`/`rtl`, 번역이 누락되었는지 여부, 다른 로케일
`etag`	리비전의 ETag

해당 경로에 게시된 것이 없으면 404입니다. hidden이 true인 섹션은 건너뛰세요. head 사용법은 검색 및 AI 답변을 참고하세요.

`GET /preview/pages?token=…&locale=en`

미리보기 링크용 초안 페이지입니다. 개발 환경 전용입니다(프로덕션에서는 404). 절대 캐시하지 마세요. 잘못된 토큰이면 403 PREVIEW_INVALID, 15분이 지나면 410 PREVIEW_EXPIRED입니다.

`GET /entries?collection=projects`

컬렉션의 항목입니다.

매개변수	예시	비고
`collection`	`projects`	필수
`locale`	`ar`
`filter`	`category:water,featured:true`	`field:value` 쌍, 쉼표로 구분
`sort`	`-publishedAt`, `title`, `slug`, `featured`, `field.year`	내림차순은 `-`를 앞에 붙입니다
`fields`	`title,slug,image`	이 필드만 반환
`limit`	`20`	최대 100. 항상 지정하세요. 지정하지 않으면 응답이 커질 수 있습니다
`page`	`2`

entries, assets, meta.pagination을 반환합니다.

`GET /feed?collection=news&limit=20`

RSS와 뉴스 목록을 위한 편집용 컬렉션의 최신 항목입니다. 다른 컬렉션에는 404 FEED_NOT_EDITORIAL입니다.

`GET /globals?locale=en`

site-header, site-footer 같은 공유 콘텐츠입니다. { globals: { key: { data, revision, publishedAt } }, assets }.

`GET /redirects`

{ redirects: [{ from, to, status }] }. 미들웨어나 next.config 리디렉션에 적용하세요.

`GET /media/{assetId}?rendition=…`

15분간 유효한 서명된 이미지 URL로 리디렉션(302)합니다. 토큰이 필요 없으므로 <img src>에 사용할 수 있습니다.

`GET /sitemap.xml`, `GET /robots.txt`, `GET /llms.txt`

사이트 루트용 파일이며 라이브 릴리스(프로덕션)로 만들어지거나 잠겨 있습니다(개발: 빈 사이트맵, Disallow: /, X-Robots-Tag: noindex, nofollow). 토큰이 서버에 남도록 내 도메인에서 프록시하세요. 검색 및 AI 답변을 참고하세요. 환경에 웹사이트 주소가 생길 때까지는 409 SITE_ADDRESS_MISSING입니다.

배포 보고

웹사이트가 시작될 때 호출하는 POST /deployments입니다.

{
  "bundleDigest": "<sha256 hex of the contract bundle this build renders>",
  "bundleVersion": "1.4.0",
  "commit": "a1b2c3d",
  "components": [{ "id": "acme.home.hero", "version": "1.0.0" }],
  "runtime": "node",
  "siteOrigin": "https://dev.example.com"
}

응답의 state는 in-sync, missing-components, different-contract, unknown-contract, no-contract 중 하나이며 활성 다이제스트와 누락된 컴포넌트가 함께 제공됩니다. runtime은 node 또는 cloudflare-workers입니다. 컴포넌트는 최대 500개입니다.

오류

오류는 안정적인 code를 가진 JSON입니다. 제한과 오류를 참고하세요.

기본 URL과 인증

캐싱

엔드포인트

GET /site

GET /routes

GET /pages?route=/about&locale=en

GET /preview/pages?token=…&locale=en

GET /entries?collection=projects

GET /feed?collection=news&limit=20

GET /globals?locale=en

GET /redirects

GET /media/{assetId}?rendition=…

GET /sitemap.xml, GET /robots.txt, GET /llms.txt