Concepts
Objects

An object is any piece of content in your space — a page, weblink, tag, daily note instance, or custom type. The primary representation is returned by GET /object.

Response shape

Field	Description
`id`	Object UUID
`structureId`	Structure / type id (see Structures)
`collections`	UUIDs of collections (databases) this object is assigned to
`properties`	Map of property definition id → typed value (see Properties)
`blocks`	Optional map of property id → block content
`files`	Optional signed download URLs for media types
`mediaContent`	Optional OCR text and colors for images when analysis is complete

Example (abbreviated):

{
  "id": "7d2e7f8a-4c3b-4e1d-9f0a-123456789abc",
  "structureId": "4ba6e5c6-3f31-45f2-93a0-27a8b2d91551",
  "collections": ["9f20f3d7-7df6-4b4a-8f82-123456789abc"],
  "properties": {
    "title": { "type": "title", "title": { "value": "Example" } }
  },
  "blocks": {
    "content": [
      {
        "id": "b1111111-1111-4111-8111-111111111111",
        "type": "TextBlock",
        "tokens": [{ "type": "TextToken", "text": "Hello", "style": {} }],
        "blocks": [],
        "hierarchy": { "key": "Base", "val": 0 }
      }
    ]
  }
}

Collections

Collections are Capacities databases that group objects of a structure. On read, collections lists the collection ids the object currently belongs to.

When creating or updating:

Pass specific collection ids to assign the object to those databases.
Pass collections: [] to move the object back to its default database for that structure (when the structure supports collections).
Omit collections on create to use default placement behavior.

Only structures that support collections accept collections on POST /object and PATCH /object. Others ignore or reject collection changes.

CRUD overview

Operation	Endpoint	Required scope
Read	`GET /object?id=…`	`api:read`
Create	`POST /object`	`api:write`
Update	`PATCH /object`	`api:write`
Delete	`DELETE /object?id=…`	`api:write`
Create from URL	`POST /object/url`	`api:write`
Export Markdown	`GET /object/markdown?id=…`	`api:read`
Create from Markdown	`POST /object/markdown`	`api:write`

Patch requires at least one of properties or collections. Delete supports hardDelete=true to permanently remove an object instead of moving it to trash.

To create or export body content as Markdown instead of block trees, see Markdown.

Listing objects

Beyond fetching a single object with GET /object, three endpoints return pages of object summaries — the same lightweight { id, structureId, title } shape used by search:

Endpoint	Lists objects…	Required scope
`GET /objects/structure?id=…`	…of a given structure (object type)	`api:read`
`GET /objects/tag?id=…`	…that have a given tag	`api:read`
`GET /objects/collection?id=…`	…assigned to a given collection (database)	`api:read`

Each is cursor-paginated and accepts:

Query param	Description
`id`	Structure, tag, or collection id to filter by — required
`pageSize`	Results per page. Defaults to 100, maximum 100
`cursor`	Opaque cursor from the previous page's `nextCursor`. Omit to fetch the first page

Response shape:

{
  "results": [
    { "id": "7d2e7f8a-4c3b-4e1d-9f0a-123456789abc", "structureId": "RootPage", "title": "Project Alpha" }
  ],
  "nextCursor": "9f20f3d7-7df6-4b4a-8f82-123456789abc",
  "hasMore": true
}

Field	Description
`results`	Object summaries for this page
`nextCursor`	Pass as `cursor` to fetch the next page. `null` on the last page
`hasMore`	`true` if another page is available

Keep fetching while hasMore is true:

import { CapacitiesClient } from '@capacities/api'

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

let cursor: string | undefined
const allResults = []

do {
  const page = await capacities.objects.structure({
    structureId: 'RootPage',
    cursor,
    pageSize: 100,
  })
  allResults.push(...page.results)
  cursor = page.hasMore ? (page.nextCursor ?? undefined) : undefined
} while (cursor)

The same loop applies to capacities.objects.tag({ tagId }) and capacities.objects.collection({ collectionId }). Each endpoint has its own rate limit — see Rate Limiting.

Looking for objects by title instead of by structure, tag, or collection? Use POST /objects/search (capacities.objects.search) — it's relevance-ordered and returns a single page (no cursor).

Media analysis (`mediaContent`)

For images (MediaImage), GET /object may include mediaContent when AI analysis is complete (mediaContentState is full):

Field	Description
`ocr.text`	Text extracted from the image
`colors`	Dominant colors (`name`, `hex`)

Other media types and fields (audio, weblinks, categories, etc.) are not exposed yet. While analysis is still running or failed, mediaContent is omitted.

Are you missing something in the documentation?

Create a ticket on our feedback board. - Let us know if you have an idea for a feature, improvement or think there is something missing.

Request additions to the documentation. - If your questions are not getting answered, let us know and we will extend the documentation.

Markdown

Properties

ConceptsObjects