Skip to content

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”.

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
Terminal window
curl https://api.erreos.com/api/v1/content/entries?collection=blog \
-H "Authorization: Bearer erre_sk_..."

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" | undefined

A 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.

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.

{
"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.

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.

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
Terminal window
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=1 they read the draft.
  • An absent field matches nothing, false included: filter.destacado=false returns 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 not true/false, an empty value or a fourth filter is 400 invalid_param. A select with no options yet cannot be filtered.
  • Filters compose with sort, slug, limit and cursor, and are part of the ETag.

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.

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 ?? [].

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:

Terminal window
curl -sS https://api.erreos.com/api/v1/content/types.ts \
-H "Authorization: Bearer $ERRE_TOKEN" -o src/lib/erre.ts

Once @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 select is the union of its option values, retired options included;
  • a list is an array of a <Name><Field>Row interface;
  • a reference names its collection and types the keys it carries;
  • a format never changes the type: a money field is a number;
  • a retired field is still there, marked @deprecated, and a field taken off the website is not;
  • a <Name>Filters lists what filter accepts: a select’s option values, a boolean, one tag, a reference’s slug or id;
  • ERRE_CONTRACT holds every collection’s contractRevision;
  • ErreCollectionEntries and ErreCollectionFilters map each key to its types, and a declare 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 contractRevision is asserted rather than merely logged.

?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: 7
published_at: "2026-09-14T15:04:05.000Z"
order: 3
contract_revision: 12
seo:
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.

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.

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.

Terminal window
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.

?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.

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 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.

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.