Delivery API

從 Atlas 讀取已發布的頁面、項目、全域內容、路由與重新導向，並回報您網站的建置。

本頁翻譯自英文。若內容有任何差異，以英文版為準。閱讀英文版

Delivery API 是您的網站讀取已發布內容的方式。請只從伺服器端程式碼呼叫它。

基礎 URL 與驗證

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

每個權杖屬於單一環境。Development 與 Production 有各自的權杖。
權杖為 43 個隨機字元，只會顯示一次，有效期間為 1 至 365 天，且可隨時在 Studio 中撤銷。Atlas 只儲存指紋。
Production 權杖只能讀取該環境的正式上線發行版本。

快取

已發布的回應會附帶：

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

請在 If-None-Match 中送出最後一個 ETag；若內容沒有變更，Atlas 會回應 304 Not Modified。搭配 Webhook，即可在發布時重新整理。預覽與部署的回應為 private, no-store。

端點

`GET /site`

環境、其正式發行版本（Production）、內容版本，以及使用中合約的摘要值與版本。

`GET /routes`

每個已發布的路由，供您的 sitemap 與靜態產生使用：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[]`，或 `null` 並附 `headProblem`
`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`

供預覽連結使用的草稿頁面。僅限 Development（在 Production 上回應 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 }] }。請在您的 middleware 或 next.config 的 redirects 中套用。

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

重新導向（302）到有效期 15 分鐘的已簽署圖片 URL。不需要權杖，因此可用於 <img src>。

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

供您網站根目錄使用的檔案，依據正式發行版本（Production）建立，或加以鎖定（Development：空的 sitemap、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