Response values

Entry fields come back directly in the response, keyed by field ID. The shape can differ from the internal data the dashboard saves, so use the delivery API's shape in your site.

Fields added automatically

Dates are ISO 8601 strings. Convert them to the time zone you need when your app displays them. If you pass fields, meta fields other than id are also selectable.

publishedAt isn't the last-updated time. Use updatedAt to show updates. The status and draftKey aren't included in the meta fields of regular delivered entries.

For multilingual APIs, createdAt, updatedAt, and publishedAt are also the dates of the language version actually returned. An extra _langs field is added only when you pass include=_langs.

{ "_langs": { "current": "en", "available": ["ja", "en"] } }

If the response fell back, current is the main language that was actually returned, not the language you asked for. available lists only live languages. See Multilingual delivery for details.

Strings, numbers, and choices

Optional fields, and entries created under an earlier schema, may have no value. Even when the type is defined, handle the case where it isn't filled in.

Images and files

{  "eyecatch": {    "url": "https://media.genko.me/example/image.webp",    "alt": "Writing a draft in a notebook"  },  "gallery": [    { "url": "https://media.genko.me/example/detail.webp", "alt": "A close-up of the notebook" }  ],  "document": "https://media.genko.me/example/document.pdf"}

The URLs above only show the shape. Get real URLs from the response. An image is url and alt, multiple images are an array of those, and a file is a URL string. Internal media IDs aren't part of delivered values.

Images inside rich text are also resolved to the URL in the img element at delivery time. To keep up with replacements, don't keep using an old URL you stored. Fetch the entry again.

Entry references

The shape of a reference changes with depth. Once expanded, it's an object like any other entry, with id, its fields, and its dates. When expanded, an unpublished referenced entry becomes null for a single reference and is dropped from the array for multiple references. With depth=0, or when the referenced API isn't allowed by the key, the value stays an ID.

The type of the referenced entry isn't inferred automatically. The CLI's generated types use unknown for a single reference and unknown[] for multiple references. For the conditions under which references expand, and what happens when there's no API setting, see the query reference.

Integration block

For the saved provider-specific value, embedUrl is added only when one can be generated. For Google Maps, YouTube, Figma, CodePen, and CodeSandbox, it returns a URL for embedding. See Integration blocks for supported services and how to enter them.

embedUrl isn't always present. For providers that aren't generated, such as Google Drive, Dropbox, and X, the key itself is omitted. Check that the value is a string before you pass it to an iframe, and when it's missing, show something suited to the provider. A Dropbox value doesn't include the public share URL.

Types and real data

The SDK returns the JSON it fetched as the TypeScript type you specify. It doesn't validate the whole response at runtime.

In particular, with fields narrowed by fields, reference shapes changed by depth, and optional fields, the type alone can't guarantee that the real data exists. Validate values in your app where you need to.