API Reference

References, files, and depth

How linked entries and uploaded files come back in API responses.

Reference depth

Reference fields store entry ids. Pass ?depth=N to expand them into the referenced entries' data:

depth=0	Raw ids only. Default for lists — fast and light.
depth=1	Referenced entries expanded one level. Default for single reads.
depth=2+	Nested references expand too — bounded and cycle-safe, so self-referencing content can't loop.

// depth=0                    // depth=1
"author": "68b1f0c2…"    →    "author": {
                               "id": "68b1f0c2…",
                               "status": "published",
                               "slug": "ada",
                               "data": { "name": "Ada" }
                             }

A resolved reference is { id, status, slug, data }. Relation fields holding many references come back as an array of these.

Missing references

A reference can point at an entry that was deleted, or that isn't published. Rather than dropping it silently, the API returns a tombstone so array positions stay stable:

"relatedPosts": [
  { "id": "68b1f0c2…", "status": "published", "slug": "faster-sites",
    "data": { "title": "5 Tips for Faster Sites" } },
  { "id": "6a3848e3…", "missing": true }   // deleted or unpublished
]

Always guard for it when mapping references — check !ref.missing (or that ref.data exists) before reading fields:

const posts = (data.relatedPosts ?? [])
  .filter((ref) => !ref.missing)
  .map((ref) => ref.data)

Field keys & API names

Everything under data is keyed by each field's API name (not its display name). If an API name contains a hyphen or other non-identifier character, dot access won't parse in JS/TS — use bracket access:

data.title            // ok — simple identifier
data['related-posts'] // hyphenated API name — bracket access required
data.related-posts    // ✗ parses as (data.related - posts)

Tip: prefer camelCase or snake_case API names when creating fields, so they stay valid identifiers on the consuming side.

Files

File and image fields are stored by id, but the API always resolves them to the file's info — you never have to look up file ids yourself:

"coverImage": {
  "url": "https://…/cover.png",
  "name": "cover.png",
  "type": "IMAGE"
}