交付 API

从 Atlas 读取已发布的页面、条目、全局内容、路由和重定向，并报告您网站的构建。

本页面由英文翻译而来。如有任何差异，以英文版本为准。阅读英文版

交付 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。将其与 Webhook 结合使用，即可在发布时刷新。预览和部署的响应为 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=…`

重定向（302）到有效期为 15 分钟的已签名图片 URL。无需令牌，因此可用于 <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