# SDK

Source: https://capacms.com/docs/sdk

@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](https://capacms.com/docs/api).

```sh
pnpm add @capacms/sdk@next
```

It 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.