cURL

curl --request GET \
  --url https://api.nohead.io/v1/collections/{collection_id}/search \
  --header 'Authorization: Bearer <token>'

import { Nohead } from "@nohead/sdk"

const nohead = new Nohead()

for await (const record of nohead.records.search("posts", "hello", {
  filter: { published_at: { exists: true } },
  sort: "-published_at",
  expand: ["author"],
})) {
  console.log(record)
}

from nohead import Nohead

nohead = Nohead()

for record in nohead.records.search(
    "posts",
    "hello",
    filter={"published_at": {"exists": True}},
    sort="-published_at",
    expand=["author"],
):
    print(record)

require "nohead"

nohead = Nohead::Client.new

nohead.records.search("posts", "hello", filter: { published_at: { exists: true } }, sort: "-published_at", expand: ["author"]).each do |record|
  puts record
end

{
  "data": [
    {
      "id": "rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
      "object": "record",
      "collection_id": "<string>",
      "collection": "<string>",
      "published_at": "2023-11-07T05:31:56Z",
      "revision": 123,
      "schema_version": 123,
      "history_pruned_through": 123,
      "deleted_at": "2023-11-07T05:31:56Z",
      "purge_after": "2023-11-07T05:31:56Z",
      "data": {
        "title": "Introducing Foo",
        "body": {
          "type": "doc",
          "content": []
        }
      },
      "created_at": "2026-09-27T12:00:00.000Z",
      "updated_at": "2026-09-27T12:00:00.000Z",
      "expanded": {}
    }
  ],
  "meta": {
    "next_cursor": "<string>",
    "has_more": true,
    "total_estimate": 123
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

Search records

Full-text search in a collection, ranked by relevance (or sort). Anyone who can read the collection can search it, and the words match its searchable fields. Filters work as in the records list, on published_at and on fields marked filterable (not on deleted or the other timestamps); sort on created_at, updated_at, published_at and fields marked sortable (- for descending). Results are the current records; changes appear within seconds. At most the first 1,000 hits can be paged through. expand embeds related records and assets as in the records list. 409 with a detail code: index_building while a new collection’s index is first built, and rebuilding when filtering or sorting on a field newly made filterable or sortable, or searching words while the index is rebuilt for a field’s new key, until the rebuild that adds it has run (the index status is stale meanwhile).

GET

collections

{collection_id}

cURL

curl --request GET \
  --url https://api.nohead.io/v1/collections/{collection_id}/search \
  --header 'Authorization: Bearer <token>'

import { Nohead } from "@nohead/sdk"

const nohead = new Nohead()

for await (const record of nohead.records.search("posts", "hello", {
  filter: { published_at: { exists: true } },
  sort: "-published_at",
  expand: ["author"],
})) {
  console.log(record)
}

from nohead import Nohead

nohead = Nohead()

for record in nohead.records.search(
    "posts",
    "hello",
    filter={"published_at": {"exists": True}},
    sort="-published_at",
    expand=["author"],
):
    print(record)

require "nohead"

nohead = Nohead::Client.new

nohead.records.search("posts", "hello", filter: { published_at: { exists: true } }, sort: "-published_at", expand: ["author"]).each do |record|
  puts record
end

{
  "data": [
    {
      "id": "rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
      "object": "record",
      "collection_id": "<string>",
      "collection": "<string>",
      "published_at": "2023-11-07T05:31:56Z",
      "revision": 123,
      "schema_version": 123,
      "history_pruned_through": 123,
      "deleted_at": "2023-11-07T05:31:56Z",
      "purge_after": "2023-11-07T05:31:56Z",
      "data": {
        "title": "Introducing Foo",
        "body": {
          "type": "doc",
          "content": []
        }
      },
      "created_at": "2026-09-27T12:00:00.000Z",
      "updated_at": "2026-09-27T12:00:00.000Z",
      "expanded": {}
    }
  ],
  "meta": {
    "next_cursor": "<string>",
    "has_more": true,
    "total_estimate": 123
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Project-scoped API key, e.g. nohead_sk_k7fz0a9c3m2q_<secret>, or nohead_pk_… for a published-only key. Used by servers, CI, the CLI and coding agents.

Path Parameters

collection_id

string

required

Collection ID, or the collection slug when authenticating with an API key.

Query Parameters

rich_text

enum<string>

default:document

How rich text fields read in the records and drafts returned (and in records they embed with expand): document, the stored ProseMirror JSON document; html, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or markdown (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no expand: in HTML a WebP rendition at most 1600 pixels wide with its width and height (an SVG as itself), in Markdown the asset's image_url. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.

Available options:

document,

html,

markdown

string

The words to search for; empty matches everything.

limit

integer

default:20

Page size.

Required range: 1 <= x <= 100

cursor

string

The next_cursor from the previous page.

filter

object

filter[<key>]=value (equal), or filter[<key>][<operator>]=value; filters combine with AND. Keys are field keys, published_at, deleted (true lists soft-deleted records instead) and, in record lists and counts, created_at and updated_at.

eq, ne: equal, not equal. For fields with several values, "contains" and "does not contain". ne matches records with no value.
gt, gte, lt, lte: integer, decimal and date fields with one value, and the timestamps.
in: any of up to 100 comma-separated values (\, is a comma inside a value, \\ a backslash); for fields with several values, "contains any of".
exists: true for records with a value, false for those without (and published_at: published or not).

Values are parsed per field type ("5" is not the integer 5), but not held to the field's limits or format (price[lt]=10 works when max is 5; a slug filter that isn't a slug matches nothing). Dates take today, and dates with a time now too. A day (YYYY-MM-DD) given for a date with a time, or a timestamp, covers that day in the field's time_zone (UTC without one): gte from its start, lte to its end, eq within it. A date with a time matches the same moment written with any offset.

Show child attributes

sort

string

expand

string

Comma-separated relation, asset or rich text field keys whose records or assets to embed under expanded (at most 5); for a rich text field, the assets its images show. Embedding needs permission to read what is embedded: records:read for relations, assets:read for assets and rich text (403 otherwise).

Response

A page of matching records.

data

object[]

required

Show child attributes