Delivery API

Atlas から公開済みのページ、エントリー、グローバル、ルート、リダイレクトを読み取り、ウェブサイトのビルドを報告します。

このページは英語から翻訳されたものです。内容に相違がある場合は、英語版が優先されます。英語版を読む

Delivery API は、ウェブサイトが公開済みコンテンツを読み取るための手段です。サーバーコードからのみ呼び出してください。

ベース URL と認証

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

各トークンは 1 つの環境に属します。開発環境と本番環境では、トークンが別々です。
トークンはランダムな 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`

公開済みの 1 ページ。

フィールド	内容
`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`

プレビューリンク用の下書きページ。開発環境のみです（本番環境では 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