docs menu

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.

bash
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}'
json
{
  "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#

InputTypeDefaultWhat it does
typestring or string[]all typesDocument types to return
idsstring[]Only these ids (up to 1,000)
whereobjectFilter, below
searchstringFull text search on titles and text fields
orderstring or { field, dir }[]most recently updated firstSort order, below
limitnumber501 to 1,000
offsetnumber0Skip this many results
selectstring[]all fieldsFields to return
expandnumber or { type: fields }0Follow references this many levels deep, up to 3, or keep chosen fields per referenced type
langstringReturn one language
fallbackbooleanfalseWith 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
branchstring"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:

json
{
  "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:

json
{ "where": { "or": [{ "category": "news" }, { "featured": true }], "not": { "draftNote": { "exists": true } } } }
OperatorMatches when the field
eqequals the value (a bare value means eq)
nediffers from the value
gt, gte, lt, ltecompares greater or lower; numbers compare as numbers, strings (dates included) as text
in, ninis one of, or none of, a list of values
containscontains the text, ignoring case
includesis a list that holds the value
existshas 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:

json
{ "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:

json
{ "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:

json
{ "type": "page", "expand": { "project": ["title", "slug", "cover"], "*": ["title", "slug"] } }
json
{ "_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.

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

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