In this section · 5 articles

Delivery API: addresses, parameters and responses

The public delivery API's two addresses, how to send a key, every query parameter, the JSON a Single, a Collection and one item return, status codes, caching, CORS and rate limits.

Applies to
Headless CMS 1.0 and later
Who can do this
Developer
Where
Headless CMS › Delivery › API explorer
On this page

Websites and apps read published content with plain GET requests. Drafts are never reachable from this API. To try any request against your own content, use the API explorer. The OpenAPI description, Headless CMS Delivery API, is listed in Developer Tools › API Documentation.

The examples use https://laramin.example.com for your Laramin's address, a space with the key company, and the schemas site_header (a Single) and faqs (a Collection).

Addresses

MethodPathReturns
GET
/api/v1/public/hcms/{space}/{schema}
A Single's one object, or one page of a Collection.
GET
/api/v1/public/hcms/{space}/{schema}/{item}
One Collection entry, by its published address (slug) or its public id.

{space} and {schema} are the keys shown on their pages. HEAD works on both and returns no body.

Bash
curl "https://laramin.example.com/api/v1/public/hcms/company/faqs?locale=en&per_page=10"

Replace the highlighted values with your own.

Keys

SpaceNo keyValid key, grantedValid key, not grantedInvalid key
PublicRead as anonymous.Read as the application: its default channel and version pin apply.Read as anonymous.Ignored; read as anonymous.
Restricted401Read as the application.404, as if the space didn't exist.401

Send the key in one of these headers:

Bash
curl -H "X-Api-Key: $LARAMIN_API_KEY" "https://laramin.example.com/api/v1/public/hcms/partners/price_list"
curl -H "Authorization: Bearer $LARAMIN_API_KEY" "https://laramin.example.com/api/v1/public/hcms/partners/price_list"

Keys are issued in Developer Tools › API Consumers. Keep them on a server, in a mobile app or in a build tool. A browser page can't send one: the API's CORS rules allow no request headers. See Give an application access to a content space.

Query parameters

These are the only parameters. An unknown, repeated, bracketed or empty-valued parameter gets a 422. ?fields=, ?filter[...] and ?page[size]= are refused too.

ParameterUseValuesWhen left out
channelOnly entries shown on this channel.An active channel's key, for example web.The application's default channel, else only entries shown on All channels, or a 422 if the space refuses requests that name no channel.
localeThe language to send.A language the space offers, for example hi.The space's default language. Accept-Language is never read.
versionThe schema version to send.A served major version, for example 2.The application's pin, else the oldest served version.
includeExpand Reference fields into the linked entries.Comma-separated Reference field keys, up to 3 by default.References are sent as stubs.
pageCollection lists only.1 or more, up to the last page.1
per_pageCollection lists only.1 to the space's maximum page size (100 by default).The space's default page size (20 by default).
sortCollection lists only.order (the editors' order), published_at, -published_at, title.order

page, per_page and sort on a Single or on one item get a 422.

Responses

Every answer uses Laramin's API envelope: success, message, data, meta, and for lists links.

One entry

data is one object for a Single or for one item:

JSON
{
  "success": true,
  "message": "Success",
  "data": {
    "id": "01JBXKQ4ZP0M5V3W7H2R9T6Y8E",
    "slug": "opening-hours",
    "type": "faqs",
    "locale": "en",
    "published_at": "2026-11-02T09:30:00Z",
    "fields": {
      "question": "When are you open?",
      "answer": "<p>Monday to Friday, 9:00 to 17:00.</p>",
      "category": { "id": "01JBXKR1C8D2F4G6H8J0K2M4N6", "slug": "visiting", "type": "faq_categories" }
    }
  },
  "meta": {
    "request_id": "…",
    "locale": "en",
    "space": "company",
    "schema": "faqs",
    "schema_version": "1.2",
    "schema_versions_served": [1],
    "channel": null,
    "locale_fallback": false
  }
}
Item fieldMeans
idThe entry's public id, the same in every language and never reused.
slugIts web address, or null for a Single.
typeThe schema's key.
localeThe language actually sent. It differs from the one asked for when the entry fell back.
published_atWhen this language was last published, in UTC.
fieldsThe delivered fields, by key, in the order the schema sets. Hidden fields are left out entirely. Each value's form follows its field's API format.

A Collection's list

data is an array of the same objects. meta adds current_page, per_page, count, last_page and total, and links holds self, first, prev, next and last. A Collection with nothing published returns an empty array.

If a page would be larger than the response size budget (5 MB by default), it stops early, never mid-item, sets meta.budget_reduced to true, and links.next continues from the next item.

Meta

KeyMeans
schema_versionThe version sent, for example 1.2.
schema_versions_servedEvery major version still served, for example [1, 2].
newer_versionPresent when a newer major than the one sent is served. Time to move.
channelThe channel applied, or null.
localeThe language asked for, or the space's default.
locale_fallbacktrue when some content came from the default language, because the language asked for wasn't published or a field was empty.

References

A Reference field is sent as a stub, { "id", "slug", "type" }. Name it in include, for example ?include=category, to receive the linked entry instead. Expansion goes one level deep. A linked entry that fails any delivery check for the same caller, such as one that isn't published, is sent as null.

Status codes

Statuserror.codeWhen
200The content.
304The request's If-None-Match matches: nothing changed.
401UNAUTHENTICATEDA Restricted space, called with no key or an invalid one.
404NOT_FOUNDThe space, schema or item doesn't exist, or any delivery check fails. Every 404 has the same body.
422VALIDATION_ERRORA query parameter is unknown, repeated or out of range, including a language, version or channel the space doesn't serve. error.reason is invalid_query.
429RATE_LIMITEDToo many requests. Wait for Retry-After seconds.
500Delivery failed unexpectedly. Quote meta.request_id when you report it.

The API never answers 403 or 410, so a caller can't tell a hidden entry from a missing one. While Tell granted applications why something is hidden is on (the default), a caller with a granted key gets error.reason with a 404, for example assignment_delivery_disabled, not_published or not_shown_on_channel. Anyone else gets the identical body.

Caching

  • Every 200 has a weak ETag. Send it back as If-None-Match to get a 304 when nothing changed.
  • Anonymous answers from a Public space are Cache-Control: public, max-age=60, stale-while-revalidate=300 with the default settings. A browser or CDN may serve the previous answer for up to that long after a change.
  • Answers to a key, and every answer from a Restricted space, are private, no-cache.
  • Vary: X-Api-Key, Authorization, Accept-Encoding. Content-Language names the language sent.

CORS

Every answer carries Access-Control-Allow-Origin: *. A preflight allows GET and HEAD, no request headers and no credentials, and isn't counted against the rate limit. So a browser page can read Public spaces directly, without a key.

Rate limits

CallerLimit
With a key600 requests a minute per application.
Without a key120 requests a minute per IP address and space, and 600 a minute per IP address across all spaces.

These are the defaults; your server's settings may differ. X-RateLimit-* headers report what's left.