The Beta API has been superseded by the new API. This guide covers everything you need to update.

Authentication

This is the most significant change between the two versions.

Beta: one token for all spaces

The beta API used a single user-level API token that granted access to all your spaces. Every request that needed a specific space required you to pass a spaceId query parameter to identify which one to act on.

GET /spaces          # discover your space IDs first
GET /space-info?spaceId=<id>
POST /save-to-daily-note   # body: { spaceId: "...", mdText: "..." }

API v1: one token per space (or OAuth)

API v1 tokens are space-scoped. A personal API token or an OAuth access token grants access to exactly one space, so you never pass spaceId in a request. If you need to work across multiple spaces, create one token per space.

Authorization: Bearer cap-api-...      # API token
Authorization: Bearer eyJ...           # OAuth access token

See Authentication for how to generate a personal token or set up OAuth.

Route mapping

All functionality from the beta API is available in v1. The table below shows the direct mapping.

Per-route migration details

Spaces

Beta returned an array of all spaces the user had access to.

v1 returns the single space the token is scoped to. There is no list endpoint; each token is already tied to one space.

- GET /spaces
+ GET /space

Response shape is similar; id and title are present in both.

Space structures

Beta required a ?spaceId= query parameter.

v1 derives the space from the token.

- GET /space-info?spaceId=ac7abb59-b1fd-4102-b549-78e5443610ac
+ GET /space/structures

The response structure is equivalent: a list of structures with property definitions and collections.

Search

Beta matched objects by title and returned minimal identifiers (id, structureId).

v1 uses a richer request and response:

- POST /lookup
- { "spaceId": "...", "searchTerm": "my note" }
+ POST /objects/search
+ { "query": "my note", "structureIds": ["RootPage"] }

Response in v1 returns results: [{ id, structureId, title }]. The structureIds filter is optional; omit it to search across all types.

Weblink

Beta accepted a URL and a target space.

v1 accepts a URL with optional properties, notes (markdown), and target collections:

- POST /save-weblink
- { "spaceId": "...", "url": "https://example.com" }
+ POST /object/url
+ {
+   "url": "https://example.com",
+   "properties": {
+     "title": { "type": "title", "title": { "value": "My link" } }
+   },
+   "markdown": "Optional notes"
+ }

The v1 endpoint returns the full created object including its id.

Daily note

Beta accepted a plain mdText string and a spaceId.

v1 accepts either a markdown string or a structured blocks array (provide exactly one):

- POST /save-to-daily-note
- { "spaceId": "...", "mdText": "# Hello\nSome text" }
+ POST /blocks/daily-note/append
+ { "markdown": "# Hello\nSome text" }

Use markdown for simple text. Use blocks when you need precise control over block types and hierarchy. The endpoint processes asynchronously and returns 204 No Content.

TypeScript SDK

If you were calling the beta API directly via HTTP, the official SDK is now available. See SDKs for installation and full authentication setup, including OAuth.

The SDK method names mirror the v1 REST paths:

import { CapacitiesClient } from '@capacities/api'

const capacities = new CapacitiesClient({ apiToken: 'cap-api-...' })

const space = await capacities.space.get()
const { results } = await capacities.objects.search({ query: 'my note' })
await capacities.blocks.dailyNote.append({ markdown: '## Today\nSome text' })

Checklist

• Generate a new per-space API token in Capacities settings (Settings > Capacities API)
• Remove all spaceId parameters from request bodies and query strings
• Replace GET /spaces + GET /space-info with GET /space and GET /space/structures
• Replace POST /lookup with POST /objects/search
• Replace POST /save-weblink with POST /object/url
• Replace POST /save-to-daily-note with POST /blocks/daily-note/append (rename mdText → markdown)