Skip to content
Jetrepo
Esc
↑↓navigate↵open⌘Jpreview
On this page

Structured fields

Read relation identifiers, inline Components, Assets, and Taxonomy through REST.

REST keeps Reference, Asset, and Taxonomy values as IDs while projecting Components inline. It does not provide include, populate, or expansion parameters.

Access

Delivery keys require matching Backend and Environment scopes. In Preview, content.read gates Data Types and locales, while term.read gates Vocabularies and Term locales. A stored identifier never grants access to its target.

Resource projection

{
  "_id": "ARTICLE_ID",
  "author": "AUTHOR_ID",
  "related": ["ARTICLE_2", "ARTICLE_3"],
  "seo": {
    "_component": "seo",
    "title": "Example",
    "description": "Summary"
  },
  "hero": "ASSET_ID",
  "category": "TERM_ID"
}

Components such as seo are inline value objects and use the resource locale. They have no _id or lifecycle metadata. Every Component includes the required _component key, so generated clients can narrow nested and polymorphic Component unions safely.

When an application needs related records, collect IDs by known target type and send one bounded list request per type:

curl 'https://delivery.example.com/rest/author?ids=AUTHOR_1&ids=AUTHOR_2' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

A batch accepts at most 100 unique IDs and may be combined only with locale and render. Results use the normal list envelope in deterministic ID order. Missing or unauthorized targets are omitted without disclosing whether they exist outside the caller’s scope.

This bounds a relationship-heavy page to the root request plus one request for each distinct related target type. Map each response by _id; do not depend on input order.

Use a single-resource read when only one target is needed:

curl 'https://delivery.example.com/rest/author/AUTHOR_ID' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

Read an Asset through its Asset Data Type key to obtain file metadata and named signed image URLs. Different Asset Data Types keep distinct REST paths and generated schemas. Missing, unknown, or unauthorized targets fail according to the target resource request; do not infer their content from an identifier.

Taxonomy resources

For a Vocabulary key productCategories:

# One Term
curl 'https://delivery.example.com/rest/taxonomy/productCategories/TERM_ID' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

# A bounded set of Terms
curl 'https://delivery.example.com/rest/taxonomy/productCategories?ids=TERM_1&ids=TERM_2' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

# A page of Terms
curl 'https://delivery.example.com/rest/taxonomy/productCategories?first=25' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

# Direct children
curl 'https://delivery.example.com/rest/taxonomy/productCategories?parent=PARENT_TERM_ID' \
  -H 'x-api-key: YOUR_DELIVERY_KEY'

Term responses include fixed metadata such as _id, key, label, and breadcrumb. Custom-field filters and sorts exist only for eligible top-level, single-valued scalar fields and are documented by OpenAPI.

Was this page helpful?