Overview - Nohead

The SDKs cover every operation an API key can call, and every endpoint in the API reference shows how to call it from each. They follow the API’s conventions, so what you read about the API holds for them too.

Language	Package	Needs	Source
TypeScript and JavaScript	`@nohead/sdk`	Node 22+, Bun, Deno, Workers	nohead-io/nohead-typescript
Python (sync and async)	`nohead`	Python 3.11+	nohead-io/nohead-python
Ruby	`nohead`	Ruby 3.3+	nohead-io/nohead-ruby

This page covers what the three share. Each language’s page has its install, configuration and what is particular to it. Need an SDK in another language? Let us know which one. Meanwhile, anything can call the API over HTTP, or generate a client from /openapi.json.

Install and connect

npm install @nohead/sdk

pip install nohead

gem "nohead" # in your Gemfile

Create a client with a project API key, made under API keys in the web app. Each reads NOHEAD_API_KEY from the environment when you don’t pass one; none reads the key that nohead login saves for the CLI, so give your app a key of its own. Writing content, drafts, uploads and webhooks needs a key with Published records only off and the write scopes (records:write, assets:write, …); new keys are published-only by default. API keys belong to a project, so you never pass a project ID, and you can name collections by slug.

import { Nohead } from "@nohead/sdk"

const nohead = new Nohead() // or new Nohead({ apiKey })

from nohead import Nohead

nohead = Nohead()  # or Nohead(api_key=...)

require "nohead"

nohead = Nohead::Client.new # or Nohead::Client.new(api_key: ...)

API keys are secrets: use the SDKs on servers, never in a browser.

Read content

List methods give you a page, which you can also loop over: the SDK fetches the following pages as you go. Filters are the API’s: a value to equal, or operators such as { exists: true }.

for await (const post of nohead.records.list("posts", {
  filter: { published_at: { exists: true } },
  sort: "-published_at",
  expand: ["author"],
})) {
  console.log(post.data.title, post.expanded?.author)
}

// One page at a time
const page = await nohead.records.list("posts", { limit: 100 })
page.data // the records
page.meta.next_cursor

for post in nohead.records.list(
    "posts",
    filter={"published_at": {"exists": True}},
    sort="-published_at",
    expand=["author"],
):
    print(post.data["title"])

# One page at a time
page = nohead.records.list("posts", limit=100)
page.data  # the records
page.meta.next_cursor

nohead.records.list("posts", filter: { published_at: { exists: true } },
                             sort: "-published_at", expand: ["author"]).each do |post|
  puts post.data["title"]
end

# One page at a time
page = nohead.records.list("posts", limit: 100)
page.data # the records
page.meta.next_cursor

In TypeScript, describe a collection’s fields and its records are typed: nohead.records.get<Post>(id) makes post.data.title a string. In Python, results are Pydantic models, and a record’s values are in its data dict. In Ruby, read fields as methods or with [] (post.data["title"]); timestamps are Times.

Write content

const post = await nohead.records.create("posts", {
  data: { title: "Hello", author: "rec_01J9ZQ3F8X" },
})
await nohead.records.update(post.id, { data: { title: "Hello again" } })
await nohead.records.publish(post.id)

post = nohead.records.create("posts", data={"title": "Hello", "author": "rec_01J9ZQ3F8X"})
nohead.records.update(post.id, data={"title": "Hello again"})
nohead.records.publish(post.id)

post = nohead.records.create("posts", data: { title: "Hello", author: "rec_01J9ZQ3F8X" })
nohead.records.update(post.id, data: { title: "Hello again" })
nohead.records.publish(post.id)

Every write is versioned and attributed to the key. Add a note to history with changeNote (TypeScript) or change_note (Python, Ruby).

Review changes before they go live

A draft holds changes to a record until they are merged into it, now or at a set time, while the record keeps its current content. A record has one draft at most, and a merge changes content only: a live record stays live. Agents can propose changes this way for a person to review and merge.

const draft = await nohead.drafts.create(id, { data: { title: "Hello, revised" } })
const preview = await nohead.drafts.get(draft.id) // data as the record would read
await nohead.drafts.merge(draft.id) // or drafts.schedule(draft.id, { merge_at })

draft = nohead.drafts.create(record_id, data={"title": "Hello, revised"})
preview = nohead.drafts.get(draft.id)  # data as the record would read
nohead.drafts.merge(draft.id)  # or drafts.schedule(draft.id, merge_at=...)

draft = nohead.drafts.create(id, data: { title: "Hello, revised" })
preview = nohead.drafts.get(draft.id) # data as the record would read
nohead.drafts.merge(draft.id) # or drafts.schedule(draft.id, merge_at: ...)

Retries and idempotency

Failed requests are retried twice by default:

connection errors and timeouts
429 rate_limited, waiting for Retry-After when it is at most a minute (a longer wait raises RateLimitError at once)
500, 502, 503 and 504
409 with detail code in_progress: the same write, still running

Each attempt times out after 60 seconds. Set timeout and maxRetries (max_retries) on the client to change them. TypeScript also takes them for one call, and in Python with_options returns a client with other settings. Errors and retries covers what each error means. Every write carries an Idempotency-Key that stays the same across its retries, so a retry after a lost response never writes twice. To make a write safe across retries of your own (a job that may run twice), pass the key yourself:

await nohead.records.create("posts", { data }, { idempotencyKey: `import-${row.id}` })

nohead.records.create("posts", data=data, idempotency_key=f"import-{row.id}")

nohead.records.create("posts", data: data, idempotency_key: "import-#{row.id}")

Concurrent edits

Pass the record you read as ifMatch (if_match). If someone changed it since, the API refuses the write with 412 and nothing is written.

import { PreconditionFailedError } from "@nohead/sdk"

const post = await nohead.records.get(id)
try {
  await nohead.records.update(id, { data: { title } }, { ifMatch: post })
} catch (error) {
  if (error instanceof PreconditionFailedError) {
    // changed since (now at error.currentRevision): reload, and merge or ask
  } else throw error
}

from nohead import PreconditionFailedError

post = nohead.records.get(record_id)
try:
    nohead.records.update(record_id, data={"title": title}, if_match=post)
except PreconditionFailedError as error:
    ...  # changed since (now at error.current_revision): reload, and merge or ask

post = nohead.records.get(id)
begin
  nohead.records.update(id, data: { title: title }, if_match: post)
rescue Nohead::PreconditionFailedError => e
  # changed since (now at e.current_revision): reload, and merge or ask
end

Errors

Each error type of the API is an error class: ValidationError (422), NotFoundError (404), RateLimitError (429) and so on, all subclasses of APIError. They carry the status, type, message, the request ID and the field-level details.

import { ValidationError } from "@nohead/sdk"

try {
  await nohead.records.create("posts", { data: {} })
} catch (error) {
  if (error instanceof ValidationError) console.log(error.details)
  else throw error
}

from nohead import ValidationError

try:
    nohead.records.create("posts", data={})
except ValidationError as error:
    for detail in error.details:
        print(detail.field, detail.code, detail.message)

begin
  nohead.records.create("posts", data: {})
rescue Nohead::ValidationError => e
  e.details.each { |detail| puts "#{detail.field}: #{detail.message}" }
end

Upload files

Files go straight to storage, never through the API. assets.upload does the whole flow in one call: it creates the upload, sends the bytes to storage, completes the upload (which checks the file) and returns the ready asset. Reference the asset from an asset field.

import { openAsBlob } from "node:fs"
import { imageUrl } from "@nohead/sdk/images"

// Typed by the filename (cover.jpg: image/jpeg) when the Blob has no type.
const asset = await nohead.assets.upload(await openAsBlob("cover.jpg"), {
  filename: "cover.jpg",
})
await nohead.records.update(id, { data: { cover: asset.id } })
const url = imageUrl(asset, { width: 1200, format: "webp" }) // no request

from nohead.images import image_url

asset = nohead.assets.upload("cover.jpg")  # a path, bytes or a binary file
nohead.records.update(record_id, data={"cover": asset.id})
url = image_url(asset, width=1200, format="webp")  # no request

asset = nohead.assets.upload("cover.jpg") # a path or an IO
nohead.records.update(id, data: { cover: asset.id })
url = Nohead::Images.url(asset, width: 1200, format: "webp") # no request

Images covers image URLs and the loaders for Next.js, Astro and Nuxt. To search, see API search.

Verify webhooks

Webhook requests are signed. unwrap (unwrapWebhook in TypeScript) checks the signature and the timestamp and returns the event; it raises (or throws) when either is off. Pass the raw body, before any JSON parsing.

import { unwrapWebhook } from "@nohead/sdk/webhooks"

export async function POST(request: Request) {
  const event = await unwrapWebhook(await request.text(), request.headers, {
    secret: process.env.NOHEAD_WEBHOOK_SECRET!,
  })
  if (event.type === "record.published") {
    // e.g. revalidate the record's pages
  }
  return new Response(null, { status: 204 })
}

import os

from nohead.webhooks import unwrap

event = unwrap(request.get_data(), request.headers, secret=os.environ["NOHEAD_WEBHOOK_SECRET"])
if event.type == "record.published" and event.record:
    ...  # e.g. rebuild the record's pages

event = Nohead::Webhooks.unwrap(request.raw_post, request.headers,
                                secret: ENV.fetch("NOHEAD_WEBHOOK_SECRET"))
if event.type == "record.published"
  # e.g. rebuild the record's pages
end

The same event can arrive twice: deduplicate by the webhook-id header. Webhooks covers the event types, the payload and rotating the secret.

Versions

The SDKs have their own version numbers, separate from the API’s /v1. Until 1.0, the SDKs, the CLI and the API may change in ways that break your code: pin a version, and read each release’s Breaking entries before upgrading. From 1.0, the API only adds within /v1, so an older SDK keeps working; anything an SDK depends on is deprecated at least 12 months before it is removed, and the SDKs warn when they call something deprecated. Each SDK’s releases on GitHub (linked from the table at the top) list what changed in each version.

​Install and connect

​Read content

​Write content

​Review changes before they go live

​Retries and idempotency

​Concurrent edits

​Errors

​Upload files

​Verify webhooks

​Versions

Install and connect

Read content

Write content

Review changes before they go live

Retries and idempotency

Concurrent edits

Errors

Upload files

Verify webhooks

Versions