Content
Read a workspace’s published website content: the collections it authored, their entries, and the Markdown body of any one of them.
Read Authentication first for tokens, status codes and rate limits.
Reads require a secret token (erre_sk_). A publishable token may only hold
write scopes, so there is no browser-safe way to call these endpoints, and there is
not meant to be. See Why a successful read has no CORS headers.
The scope is content:read on a workspace API key. That string also names an MCP
scope on a different credential for a different product surface, so if you are asking
a workspace admin for access, ask for “content:read on a workspace API key in
Settings, then API”.
The routes
Section titled “The routes”| Route | Returns |
|---|---|
GET /api/v1/content/collections |
the schema of every collection |
GET /api/v1/content/entries |
a page of entries, as JSON |
GET /api/v1/content/entries.md |
one entry as Markdown with frontmatter |
GET /api/v1/content/types.ts |
the schema as a TypeScript file |
curl https://api.erreos.com/api/v1/content/entries?collection=blog \ -H "Authorization: Bearer erre_sk_..."Types without a package
Section titled “Types without a package”Every route here is plain HTTPS, and Generating types gives you a
TypeScript file for your schema. Together they type a fetch with no dependency:
import type { ErreCollectionEntries } from './lib/erre'; // written by GET /types.ts
async function list<K extends keyof ErreCollectionEntries>(collection: K) { const res = await fetch(`${API}/api/v1/content/entries?collection=${collection}`, { headers: { Authorization: `Bearer ${process.env.ERRE_API_KEY}` } }); if (!res.ok) throw new Error((await res.json()).error); return (await res.json()).entries as ErreCollectionEntries[K][];}
const posts = await list('blog');posts[0]?.fields.categoria; // "guias" | "noticias" | undefinedA typed client, @erreos/content, is built and not yet on npm. When it is, it adds
listAll (follows the cursor), errors as values, typed filter keys, and
npx erre-content types to write the file above.
GET /api/v1/content/entries
Section titled “GET /api/v1/content/entries”| Parameter | Values | Notes |
|---|---|---|
collection |
a collection key | Required. The key from /collections. |
slug |
an entry slug | Returns that one entry, or an empty array. Never empty. |
sort |
published_at, order |
Default published_at, newest first. order is ascending. |
limit |
1–100 (1–25 with a body) | Default 20. |
cursor |
from pagination.cursor |
Opaque. Do not construct one. |
include |
body |
Adds the Markdown body to each entry. |
preview |
1 |
Serves drafts. Needs content:read and content:preview. |
filter.<key> |
a value | Up to three. See Filtering. |
Any other parameter is a 400 that names it. sort=title is not offered. A
parameter sent with an empty value is a 400 too, never a parameter we ignore:
?slug= from a ?? '' would otherwise return the whole collection and ?cursor=
would restart your walk at page one forever.
?slug= matches the published slug: the one in the responses above, and the one
your URLs were built from. An author renaming a draft does not move it; publishing
does. Under ?preview=1, ?slug= matches the draft’s slug instead, which is the
point of a preview.
The response
Section titled “The response”{ "ok": true, "collection": { "key": "blog", "contractRevision": 12, "publishedCount": 42 }, "pagination": { "limit": 20, "hasMore": true, "cursor": "eyJ2IjoxLCJwIjoi..." }, "entries": [ { "id": "k57d8k2m4n6p8q0r2s4t6u8v", "collection": "blog", "slug": "como-cotizamos-una-cocina", "title": "Cómo cotizamos una cocina", "status": "published", "revision": 7, "order": 3, "publishedAt": "2026-09-14T15:04:05.000Z", "contractRevision": 12, "seo": { "title": "Cómo cotizamos una cocina a medida", "description": "Los tres números detrás de cada presupuesto.", "image": { "url": "https://.../og.jpg", "width": 1200, "height": 630 } }, "fields": { "resumen": "Los tres números detrás de una cotización.", "categoria": "guias", "autor": { "id": "k17c9...", "collection": "team", "slug": "ana-ruiz", "title": "Ana Ruiz", "fields": { "rol": "Directora" } } } } ]}Everything we own is at the top level; everything the workspace authored is under
fields. That is why a workspace can name a field status or revision without
colliding with ours.
title and slug are top-level, never inside fields. entry.fields.title
reads undefined forever. There is no 404 and no error, just a blank heading on your live page.
/collections marks every key with location: "top" or "fields" so a codegen
cannot get this wrong.
An absent field has no key. It is not null, not "", not a zero. That holds whether
the field is required, retired, taken off the site, or a reference whose target was
archived. So if (!entry.fields.resumen) is correct for every type and every kind of
absence, and === null is correct for none of them.
seo is the author’s meta tags, top-level because every entry has one and no
workspace declares it: title, description and image (the same shape as an image
field), each optional. An entry with none written has no seo key, so read it as
entry.seo?.title ?? entry.title.
Values are untagged: fields.resumen is the string, not { type, value }. You cannot
tell text from url from select by looking at an entry. That is what
/collections is for.
| Type | On the wire |
|---|---|
text |
string |
number |
number |
boolean |
boolean |
date |
"YYYY-MM-DD", a calendar day with no timezone and no time |
select |
the option’s value, never its label |
tags |
array of strings |
url |
string |
image |
{ url, alt?, width?, height? } |
gallery |
array of the above |
file |
{ url, name, mime, bytes } |
reference |
see References |
list |
array of row objects (see below) |
publishedAt is the only ISO-8601 value in the payload. Everything else that looks
like a date is a date field and is a calendar day.
Image and file URLs are permanent, and public from the moment they upload
Section titled “Image and file URLs are permanent, and public from the moment they upload”An image, gallery or file url is an absolute address on a public bucket. It
does not expire, it carries no token, and it works for a crawler, a static build and
a link unfurler. That is the point, since none of those can present a credential.
The corollary is that an image is fetchable by anyone holding its URL as soon as it uploads, weeks before its entry is published. Nothing about a draft, an archive or a retired field changes that; what protects an unannounced photograph is that its URL has never been given out. Treat a preview build’s image URLs as published.
A URL stops working thirty days after a publish replaces the image behind it. Copy the bytes if you need your own permanent copy; do not cache the URL and assume the object.
A list is an array of rows, and every row must be probed
Section titled “A list is an array of rows, and every row must be probed”// ✓ A list with no rows is omitted entirely, so the `?? []` is not optional.(entry.fields.hours ?? []).map((row) => `${row.day}: ${row.opens ?? 'closed'}`);// ✗ Throws on the first entry nobody filled the field in on.entry.fields.hours.map(...)Rows are ragged. The absent-key rule applies inside a row exactly as it applies
between entries: a row where nobody filled closes has no closes key. That is
different from top-level raggedness and it catches people out. Check every key you
read out of a row.
Reading every entry
Section titled “Reading every entry”Follow pagination.hasMore. There is no offset and no cap.
const entries = [];let cursor;do { const url = new URL('https://api.erreos.com/api/v1/content/entries'); url.searchParams.set('collection', 'blog'); url.searchParams.set('limit', '100'); if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ERRE_TOKEN}` } }); if (!res.ok) throw new Error(`ErreOS ${res.status}: ${(await res.json()).error}`);
const page = await res.json(); entries.push(...page.entries); cursor = page.pagination.cursor;} while (cursor);collection.publishedCount is advisory. Draw a progress bar with it if you like;
never loop on it. The loop condition is hasMore. A sitemap built against a count
that drifted is a sitemap missing pages under a green build.
A cursor is only valid for the query that produced it. Change sort, slug,
include, preview or a filter mid-walk and the next request is 400 invalid_cursor
rather than a page from somewhere else.
Filtering
Section titled “Filtering”filter.<key>=<value> keeps the entries whose field matches. Four field types can be
filtered, and /collections marks each such field filterable: true:
| Type | Matches when |
|---|---|
select |
the value equals one of the field’s option values |
boolean |
the value is true or false, as sent |
tags |
the entry has that tag |
reference |
the target’s slug or id. A catalog reference matches by id |
curl "https://api.erreos.com/api/v1/content/entries?collection=blog&filter.categoria=guias&filter.destacado=true" \ -H "Authorization: Bearer erre_sk_..."- At most three filters, combined with AND. Each key once.
- Filters read the published entry, the same values the response shows. Under
?preview=1they read the draft. - An absent field matches nothing,
falseincluded:filter.destacado=falsereturns the entries where someone set it to false, not the ones nobody touched. - A reference matches the slug frozen when the referring entry was last published (see References). A target renamed since then still matches by its id.
- A key that names no field is
400 unknown_param. A field that cannot be filtered (text, number, date, url, media, list), a select value that is not one of its options, a boolean that is nottrue/false, an empty value or a fourth filter is400 invalid_param. A select with no options yet cannot be filtered. - Filters compose with
sort,slug,limitandcursor, and are part of theETag.
A filtered page can be short, even empty, while hasMore is true. Fields are
not indexed, so a filtered request reads the collection in order and keeps what
matches, and it stops after 500 entries (the most a collection can have live), so a
published walk usually finishes in one request. Past that the page comes back with
what it found and a cursor. Keep following hasMore, as for any walk.
GET /api/v1/content/collections
Section titled “GET /api/v1/content/collections”Takes no parameters at all, including preview. A schema has no draft half.
This is the contract document. Each collection carries key, label, labelPlural,
icon, bodyMode, seo, schemaRevision, contractRevision and fields[]. Each
row of fields[] carries key, label, type, required, location, and then
filterable, format, currency, unit, maxItems, options, refCollection,
refTarget, refFields, itemFields, retired and replacedBy where they apply.
format says how to draw a value, never what type it is. The value under
entry.fields keeps its type. A text field may carry tel, email,
multiline or color. A number field may carry:
format |
The value | Also on the row |
|---|---|---|
money |
A number, in the currency’s major unit (1200 is $1,200) |
currency: an ISO 4217 code such as "MXN" |
unit |
A number | unit: the suffix to print after it, such as "m²" or "hrs" |
rating |
A whole number from 1 to 5, drawn as stars | nothing |
A number field with no format is a plain number.
Assert on contractRevision, never on schemaRevision. contractRevision moves
when the emitted key set or its meaning moves: a key appears, a type appears, an
option value appears or retires, field order changes, a field retires, a field stops
being served. schemaRevision moves on every schema save, a relabel included, so
asserting on it fails your 03:00 build because somebody fixed an accent in a Spanish
label at 16:00.
The system rows use the frontmatter spelling. published_at and
contract_revision appear in fields[] under those names; the JSON envelope above
spells the same two publishedAt and contractRevision. Only the
location: "fields" rows describe keys under entry.fields, which is the half a
codegen reads.
A retired collection is omitted from this document while /entries keeps
answering for it. That is the migration window, not a bug. A retired field is
still listed, flagged retired: true with replacedBy where there is a successor.
A select with no options and a list with no itemFields are legal: both keys
are omitted while empty, because a field is created in one step and configured in the
next. Code that reads them needs a ?? [].
Generating types
Section titled “Generating types”GET /api/v1/content/types.ts serves this document as a TypeScript file. Same token,
same scope, no parameters, and the same ETag and caching rules as /collections.
Write it into your project and commit it:
curl -sS https://api.erreos.com/api/v1/content/types.ts \ -H "Authorization: Bearer $ERRE_TOKEN" -o src/lib/erre.tsOnce @erreos/content is on npm, npx erre-content types --out src/lib/erre.ts writes the same file.
The file has, per collection, a <Name>Entry (the envelope, with collection as a
literal) and a <Name>Fields with every property optional: required means we
will not let an author publish without it, not that the key is on every entry you
read. Beyond that:
- a
selectis the union of its option values, retired options included; - a
listis an array of a<Name><Field>Rowinterface; - a
referencenames its collection and types the keys it carries; - a
formatnever changes the type: amoneyfield is anumber; - a retired field is still there, marked
@deprecated, and a field taken off the website is not; - a
<Name>Filterslists whatfilteraccepts: a select’s option values, a boolean, one tag, a reference’s slug or id; ERRE_CONTRACTholds every collection’scontractRevision;ErreCollectionEntriesandErreCollectionFiltersmap each key to its types, and adeclare module "@erreos/content"block types the client’s calls by collection key. Without the package installed the block does nothing.
Names come from the collection key in PascalCase (case_studies becomes CaseStudiesEntry).
Two keys that come out the same are numbered in order (CaseStudies2Entry).
Assert ERRE_CONTRACT against the live contractRevision in your build and fail on a
mismatch. The generated file can only ever grow: keys and types are immutable, and
fields and options only append, so regenerating never removes a property and never
changes one’s type.
Two things that assertion cannot tell you:
- A retired field keeps serving its last values. “Still served” is not “still correct”.
- Taking a field off the website removes its key. That is the only operation in the
system that narrows what you receive, and it is the whole reason
contractRevisionis asserted rather than merely logged.
GET /api/v1/content/entries.md
Section titled “GET /api/v1/content/entries.md”?collection= and ?slug=, both required. Returns
200 text/markdown; charset=utf-8: YAML frontmatter between --- fences, one blank
line, then the body byte for byte.
---id: "k57d8k2m4n6p8q0r2s4t6u8v"collection: "blog"slug: "como-cotizamos-una-cocina"title: "Cómo cotizamos una cocina"status: "published"revision: 7published_at: "2026-09-14T15:04:05.000Z"order: 3contract_revision: 12seo: title: "Cómo cotizamos una cocina a medida"resumen: "Los tres números detrás de una cotización."---
Todo presupuesto de cocina se arma con tres números...Every string is quoted and escaped; number and boolean are bare, so you can read
them as a number and a boolean.
An unknown or unpublished slug returns 200 with an empty body, not a 404.
Check for an empty string. A real document always opens with ---.
Its errors are JSON, not Markdown, so never branch your parser on the status
code. Check res.ok first.
The .md you download is a render, not the file we store. There is no importer:
editing one and mailing it back does nothing.
A reference is a snapshot, not a live view
Section titled “A reference is a snapshot, not a live view”A reference carries the values the target had when the referring entry was last published. It is not a join and it does not update when the target changes.
Viajes Riviera runs Tours and Hoteles. Nine published tours reference
hotel-xcaret-mexico. On Tuesday the hotel rebrands (new title, new slug) and is
republished. That publish freezes the hotel’s own snapshot and touches nothing else.
The nine tours keep serving {"slug": "hotel-xcaret-mexico", "title": "Hotel Xcaret México"} until each of them is republished, and their revision has not moved,
which is correct: nobody edited a tour.
Republishing the referring entry is what refreshes it. If a card shows an old name or links to a 404, that is the fix.
A reference to a catalog item has a different shape
({ id, target: "catalogItem", title, unit, kind }) and never carries a price. The
catalog is what a quote is built from; the website is not a second source of price.
Bodies are Markdown, not HTML
Section titled “Bodies are Markdown, not HTML”A body is the bytes the author typed, unrendered, including any HTML they typed.
Pass it through your own Markdown renderer. Never innerHTML.
Nothing on our side sanitizes it, and anyone in the workspace who can edit content can publish. The consuming site owns that boundary.
Caching
Section titled “Caching”Published responses carry a weak ETag and
Cache-Control: private, max-age=60, stale-while-revalidate=300. Send the tag back as
If-None-Match and an unchanged response is a 304 with no body.
curl -sS -D- -o/dev/null \ "https://api.erreos.com/api/v1/content/entries?collection=blog" \ -H "Authorization: Bearer erre_sk_..." \ -H 'If-None-Match: W/"12-40-1-9a3f1c02"'The response is private because it required a secret token. A shared cache must
never hold it. Responses also carry Vary: Authorization, and a tag is scoped to the
workspace that minted it: the URL names no tenant, so a cache that keyed on the URL
alone would serve one workspace’s content to another’s token.
On /entries, a publish, an unpublish, an archive, a reorder and taking the
collection’s entries off the site all move the tag. On /collections, any schema
save does, including a relabel, since this document prints labels.
?preview=1 responses carry Cache-Control: no-store and no ETag. Do not
cache a draft anywhere, including in a framework’s data cache.
Previewing drafts
Section titled “Previewing drafts”?preview=1 serves the draft of every entry, including never-published ones and the
unsaved-since-publish state of published ones. It needs a separate token holding
content:read and content:preview: every route on this reference checks
content:read first, and content:preview is checked on top of it. A token holding
content:preview alone is 403 forbidden_scope on every request, preview or not.
Scopes are fixed for a key’s life, so that mistake is a roll and not an edit.
Separate, because a key that can read drafts can put unfinished work on a live site.
One key holding both content:read and content:preview leaves a query parameter in
a template as the only thing between a draft and the public. Give the preview
context its own key and keep it out of the production build.
Why a successful read has no CORS headers
Section titled “Why a successful read has no CORS headers”A 200 from these routes carries no Access-Control-Allow-Origin, deliberately. A
browser therefore cannot read one.
That is the point. These endpoints need a secret token, and a secret token in a browser is the workspace’s entire content credential published in view-source. Withholding the header means that mistake fails on the machine of the person making it, instead of shipping. Call these from your server, your build, or a serverless function. Never call them from client-side JavaScript.
A 401, 403 or 429 does carry the header, so an origin-level failure is still
readable while you are debugging.
Status codes
Section titled “Status codes”| Status | error |
When |
|---|---|---|
200 |
a read, including an empty entries array |
|
304 |
your If-None-Match still matches |
|
400 |
unknown_param |
a parameter this endpoint does not take. The message names it |
400 |
missing_param |
no collection, or entries.md with no slug |
400 |
unknown_param |
a filter.<key> that names no field |
400 |
invalid_param |
a limit, sort, include, preview, empty slug, or a filter the field cannot take |
400 |
invalid_cursor |
a cursor that did not decode, was empty, or came from another |
401 |
unauthorized |
no token, wrong token, revoked, expired |
403 |
forbidden_scope |
the token lacks content:read or content:preview |
404 |
unknown_collection |
no collection with that key in this workspace |
429 |
rate_limited |
back off; honour Retry-After |
500 |
internal_error |
ours |
There is exactly one 404, and it is for a collection key. An unknown slug is a
200 with an empty array, because an entry’s absence is ordinary data. It was
probably unpublished five minutes ago, and a build that throws on that wakes somebody
for a correct state. A typo’d ?collection= is the opposite: 200 [] for
?collection=blogs would build green and ship empty.
Error bodies have no ok field at all, so body.ok === false is undefined on
every error. Branch on error, never on message. The message is written for a
developer reading a console and may change.
Rate limits
Section titled “Rate limits”120 reads per minute per token, with a burst of 240. A server-rendered site never
approaches it and a static build of a few hundred pages finishes well inside it.
include=body plus keyset paging is what keeps that true. limit=100 without a
body, limit=25 with one.
If you hit it, the number is a starting estimate rather than a measured ceiling. Tell your Erre contact what your build does; that is the conversation that moves it.