Query API
One call returns the documents a page needs. A query is JSON, sent to POST /p/<project>/v1/query, to GET /p/<project>/v1/query?q=<url-encoded JSON>, through the client's query(), or by an agent with the query tool.
curl https://api.galerne.cloud/p/acme/v1/query \
-H 'content-type: application/json' \
-d '{"type":"post","perspective":"published","where":{"featured":true},"order":"-publishedAt","limit":5}'{
"total": 12,
"items": [
{ "_id": "harbours", "_type": "post", "_rev": 7, "_createdAt": "2026-10-02T08:11:00.000Z", "_updatedAt": "2026-10-15T16:40:12.000Z", "_publishedAt": "2026-10-15T16:40:12.000Z", "title": "Harbours of Brittany", "featured": true }
]
}Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
type | string or string[] | all types | Document types to return |
ids | string[] | Only these ids (up to 1,000) | |
where | object | Filter, below | |
search | string | Full text search on titles and text fields | |
order | string or { field, dir }[] | most recently updated first | Sort order, below |
limit | number | 50 | 1 to 1,000 |
offset | number | 0 | Skip this many results |
select | string[] | all fields | Fields to return |
expand | number or { type: fields } | 0 | Follow references this many levels deep, up to 3, or keep chosen fields per referenced type |
lang | string | Return one language | |
fallback | boolean | false | With lang: use the default language where a translation is missing |
format | "markdown", "html" or "json" | "markdown" | How rich text comes back |
perspective | "published" or "drafts" | "drafts" | Published versions, or the latest edits |
branch | string | "main" | Read a content branch |
total counts every match, so you can page with limit and offset.
Filters#
where maps a field to a value, or to an object of operators:
{
"where": {
"category": "news",
"rating": { "gte": 4 },
"tags": { "includes": "brittany" },
"_publishedAt": { "gt": "2026-01-01" }
}
}Fields in one object must all match. Combine with and, or and not:
{ "where": { "or": [{ "category": "news" }, { "featured": true }], "not": { "draftNote": { "exists": true } } } }| Operator | Matches when the field |
|---|---|
eq | equals the value (a bare value means eq) |
ne | differs from the value |
gt, gte, lt, lte | compares greater or lower; numbers compare as numbers, strings (dates included) as text |
in, nin | is one of, or none of, a list of values |
contains | contains the text, ignoring case |
includes | is a list that holds the value |
exists | has a value (true) or is empty (false) |
Reach into objects with dots: seo.title, author._ref. Localized fields filter per language: title.fr. Filters can nest 8 levels deep.
System fields work in filters and in order: _id, _type, _lang, _translationOf, _createdAt, _updatedAt, _publishedAt, _title and _order.
Order#
A string of comma-separated fields, with - for descending:
{ "order": "-publishedAt,title" }or a list: [{ "field": "publishedAt", "dir": "desc" }]. Empty values come last. With search and no order, the best matches come first. Use _order for types marked orderable.
Select#
select lists the fields to return. System fields always come back. Dotted paths reach into objects and into expanded references:
{ "type": "post", "expand": 1, "select": ["title", "slug", "cover", "author.name", "author.photo"] }References#
References are stored as { "_ref": "<id>" }. With expand: 1, each one is replaced by the document it points to, in the same perspective and branch. expand: 2 also expands the references of those documents, up to 3. A reference to a document that does not exist, or is not published in the published perspective, becomes null.
Whole documents can be large: a card that points to a page would carry all of the page's blocks. Pass a map from type to fields instead, and each reference keeps only those fields. _id, _type and _lang always come. "*" stands for every type the map does not name:
{ "type": "page", "expand": { "project": ["title", "slug", "cover"], "*": ["title", "slug"] } }{ "_key": "k1", "_type": "projectCard", "project": { "_id": "proj-1", "_type": "project", "title": "Harbour", "slug": "harbour", "cover": { "asset": "m_…", "url": "…" } } }References to a type the map leaves out stay { "_ref": "<id>" }. References in blocks, objects, lists and rich text embeds expand the same way. When a chosen field is itself a reference, it expands too if its type is in the map, up to 3 levels. Field names are top level fields of the type, or the system fields _translationOf, _createdAt, _updatedAt and _publishedAt; an unknown type or field is an error.
DocsOf in the typed client types these answers from the same map; see the Next.js kit.
Languages#
With lang, localized fields collapse to their value in that language, and types with document-level translations return only documents in that language. With fallback: true, a missing value falls back to the default language, the first in languages, and a document with no translation returns its source in the default language.
{ "type": "page", "lang": "de", "fallback": true }Rich text#
Rich text comes back as Markdown by default. format: "html" returns HTML, with links to other documents and embedded media resolved to URLs. format: "json" returns the stored ProseMirror JSON, for custom renderers.
Media#
Every asset in the results gains url, mimeType, size, and width and height for images. Add transforms to the URL, such as ?w=800&fm=webp; see media.
Search#
search does full text search on titles and text fields: words, "exact phrases" and -excluded words, best matches first. Agents and the studio also have a search tool that returns ids, types, titles and a snippet.
On the Business plan, the search tool takes semantic: true to search by meaning: "articles about sailing in winter" finds posts that never use those words. It covers published content on main. Galerne turns the text into vectors with an open embedding model run by Scaleway in Paris, every minute after publishing, and stores them in your project database.
Perspectives and branches#
perspective: "published" returns published versions only. It needs no token unless the project turned public reads off, or a token with any scope. perspective: "drafts" returns the latest edits, published or not, and needs a token with the read scope.
branch reads a content branch. A branch shows its own changes and reads through to main for every document it has not changed, so previews of a branch show the whole site. A branch has its own drafts and published versions until it is promoted. See branches and review.
Sites should pass perspective: "published"; previews pass "drafts" and their branch with a read token kept on the server.
Caching#
Every answer has a tags list: what the answer depends on, for caches that purge by tag.
| Tag | When |
|---|---|
type:<type> | The query lists a type: a new document of that type changes the answer |
doc:<id> | Each document in the answer, expanded references and requested ids included |
all | The query has no type and no ids |
Past 64 documents, their types stand in for them. Webhook events carry the tags they change, so a site purges exactly the answers a publish touched. The Next.js kit does this for you.
GET /p/<project>/v1/query?q=… is cacheable. Published reads without a token answer with cache-control: public, max-age=0, s-maxage=60, stale-while-revalidate=600, so the CDN serves them for a minute and refreshes them in the background. Reads served from the CDN cache do not count as API requests.
Errors#
An unknown type or language, an invalid field path, or an operand of the wrong kind answers 400 with code invalid and a message naming the problem, such as where.rating.gt: expected a number or a string.