CapaSDK
@capacms/sdk: install it, pick an entry point, and set the environment variables it reads.
The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from your models, Next.js caching and live preview, and codegen. The API reference is at capacms.com/docs/api.
pnpm add @capacms/sdk@nextIt runs on Node 18 or later. Its types need TypeScript 5.0 or later, with
strict on or off.
| Import | What it is |
|---|---|
@capacms/sdk/next | The client for /api/: entries, GraphQL, pages and preview. It takes a cap_ key, or the legacy key a site already holds for reads. Start here. |
@capacms/sdk/nextjs | Next.js helpers: graphql() in a server component, cache tags, draft and edit mode, webhook revalidation. |
@capacms/sdk/nextjs/overlay | The live preview overlay, as a Next.js client component. |
@capacms/sdk/overlay | The same overlay without Next. |
@capacms/sdk | The legacy /v2/api client, which takes a legacy key and a tenant id and refuses a cap_ key, and the webhook signature check. |
Keys
A cap_ key is the key for /api/: scoped, and stored hashed. cap_live_
reads published content, cap_test_ drafts too. Mint one in the Capa admin
under Developers > Keys.
The legacy key your site already holds works too, for every read: a pk_
or sk_ key, or an older key with no prefix, since every key but cap_ is
a legacy key to the API. That covers entries, graphql,
graphqlSchema, pages, me, versions and preview: a site checks an
editor's preview link with the key it already holds, and Capa refuses a link
made for another project. The first client built with one prints a warning
once per process, naming the cap_ key to mint. Draft reads through the SDK
keep their rule and take a cap_ key only: draftClient's draft config,
and CAPA_DRAFT_KEY for getCapaClient and graphql(), throw a TypeError
for a legacy key before any request. An apiKey that is not a string is
refused where the client is built.
CAPA_API_URL and CAPA_KEY are the names every Capa tool reads: the
/nextjs helpers, capa-codegen and Capa's MCP server, so one .env serves
them all. capa persist registers with the development key in
CAPA_DRAFT_KEY, since only a development key stores a document (see
Persisted queries). CAPA_BASE_URL and CAPA_API_KEY still work as
aliases; when both are set, the first pair wins.
Not yet
--select-from-depth, capa convert-url, GraphQL mutations, and /api/
writes are not in this release.