# Query API

> Find documents with a JSON filter, order and page them, pick fields, follow references, choose a language and a rich text format, and read drafts or other branches.

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

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

```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 } } } }
```

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

```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](/docs/nextjs.md#create-the-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](/docs/media.md).

## 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](/docs/branches.md).

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](/docs/webhooks.md) events carry the tags they change, so a site purges exactly the answers a publish touched. The [Next.js kit](/docs/nextjs.md) 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`.
