Fetch one page

Use get when you already have a page ID, and getFirst when you have a property such as a slug. Both return the page’s properties and Markdown content. Database and property names below come from your generated schema.

Fetch by ID

An ID identifies a particular page. Use it for links that should keep working when a title or slug changes.

const [post, error] = await nc.query.blog.get("page-id-123");
if (error) throw error;
console.log(post.content);

If that page does not exist, get returns an error. The SDK does not turn it into an empty page.

Fetch by a property

A property lookup finds a page that matches your site’s rule. For example, find a published post by its slug:

import { nc } from "./notcms/schema";

const [post, error] = await nc.query.blog.getFirst({
  where: { slug: "hello-world", published: true },
});
if (error) throw error;
console.log(post?.content);

post is null when nothing matches. Your application can use that result to show a 404. A failed request is an error, not a missing page.

getFirst is available in NotCMS 0.5.0 and later. Upgrade the notcms package before using it.

Decide which match to use

where and sort work like list(). If several pages match, getFirst returns the first one in that order; it does not enforce uniqueness.

const [post, error] = await nc.query.blog.getFirst({
  where: { published: true },
  sort: { publishedAt: "desc" },
});

Use an explicit sort when “first” matters. For a slug route, keep slugs unique in your content workflow, and manage redirects when they change. See the URL recipes for language-specific slugs and ID fallbacks.

Handle the result

Outcome	`post`	`error`
A page was fetched	Page with `properties` and `content`	`null`
No `getFirst` match	`null`	`null`
A request failed	`undefined`	`Error`

Types are inferred from the generated schema. Check error before using the page; for getFirst, also handle null. See errors and rate limits for retry decisions.

Request and ordering details

getFirst sends one list request with limit=1&include=content, so only the first match and its content are transferred.
Like list, getFirst returns content already synchronized into NotCMS. Unlike get, it does not contact Notion, so changes after the last synchronization, such as a page that is no longer accessible, appear after the next sync.
With no sort, or when sort values tie, ordering uses registration order followed by page ID.
The optional third tuple value is the list response on success or no match, or the failed response on error. It is undefined for a network failure. The SDK does not retry automatically.

Getting Started

Usage

CLI Commands

Examples

Fetch one page

Fetch by ID

Fetch by a property

Decide which match to use

Handle the result

​Fetch by ID

​Fetch by a property

​Decide which match to use

​Handle the result

Fetch by ID

Fetch by a property

Decide which match to use

Handle the result