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
| Method | Path | Returns |
|---|---|---|
| GET | /api/ | A Single's one object, or one page of a Collection. |
| GET | /api/ | 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.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
curl "https://laramin.example.com/api/v1/public/hcms/company/faqs?locale=en&per_page=10"Replace the highlighted values with your own.
Keys
| Space | No key | Valid key, granted | Valid key, not granted | Invalid key |
|---|---|---|---|---|
| Public | Read as anonymous. | Read as the application: its default channel and version pin apply. | Read as anonymous. | Ignored; read as anonymous. |
| Restricted | 401 | Read as the application. | 404, as if the space didn't exist. | 401 |
Send the key in one of these headers:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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.
| Parameter | Use | Values | When left out |
|---|---|---|---|
channel | Only 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. |
locale | The language to send. | A language the space offers, for example hi. | The space's default language. Accept-Language is never read. |
version | The schema version to send. | A served major version, for example 2. | The application's pin, else the oldest served version. |
include | Expand Reference fields into the linked entries. | Comma-separated Reference field keys, up to 3 by default. | References are sent as stubs. |
page | Collection lists only. | 1 or more, up to the last page. | 1 |
per_page | Collection lists only. | 1 to the space's maximum page size (100 by default). | The space's default page size (20 by default). |
sort | Collection 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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 field | Means |
|---|---|
id | The entry's public id, the same in every language and never reused. |
slug | Its web address, or null for a Single. |
type | The schema's key. |
locale | The language actually sent. It differs from the one asked for when the entry fell back. |
published_at | When this language was last published, in UTC. |
fields | The 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. to true, and links.next continues from the next item.
Meta
| Key | Means |
|---|---|
schema_version | The version sent, for example 1.2. |
schema_ | Every major version still served, for example [1, 2]. |
newer_version | Present when a newer major than the one sent is served. Time to move. |
channel | The channel applied, or null. |
locale | The language asked for, or the space's default. |
locale_fallback | true 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
| Status | error.code | When |
|---|---|---|
200 | The content. | |
304 | The request's If-None-Match matches: nothing changed. | |
401 | UNAUTHENTICATED | A Restricted space, called with no key or an invalid one. |
404 | NOT_FOUND | The space, schema or item doesn't exist, or any delivery check fails. Every 404 has the same body. |
422 | VALIDATION_ERROR | A 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. |
429 | RATE_LIMITED | Too many requests. Wait for Retry-After seconds. |
500 | Delivery 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_, not_published or not_. Anyone else gets the identical body.
Caching
- Every 200 has a weak
ETag. Send it back asIf-None-Matchto get a304when nothing changed. - Anonymous answers from a Public space are
Cache-Control: public, max-age=60, stale-with the default settings. A browser or CDN may serve the previous answer for up to that long after a change.while- revalidate=300 - Answers to a key, and every answer from a Restricted space, are
private, no-cache. Vary: X-Api-Key, Authorization, Accept-Encoding.Content-Languagenames the language sent.
CORS
Every answer carries Access-. 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
| Caller | Limit |
|---|---|
| With a key | 600 requests a minute per application. |
| Without a key | 120 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.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.