Each structure has property definitions — the fields available on objects of that type (title, tags, dates, custom fields, and so on).

Load definitions once per session from GET /space/structures. Each entry contains:

Property value shape

On GET /object, each property is a typed object: a type field plus a nested payload with the same name. Example:

{
  "title": {
    "type": "title",
    "title": { "value": "My page" }
  },
  "tags": {
    "type": "entity",
    "entity": [{ "id": "a793dc41-a1c1-4f38-836e-6527e5a8c016" }]
  },
  "status": {
    "type": "label",
    "label": [{ "id": "opt-1", "name": "In progress" }]
  }
}

The tags field links to tag objects (RootTag) and uses the entity type. The status field is a label property (fixed options on the structure, such as on tasks).

When writing (POST /object, PATCH /object), use the same shape for fields you set. Only include keys you want to change on patch.

Supported value types

Fields not listed in propertyDefinitions for a structure, or with writable: false, cannot be set via the API.

Dates

Date properties use type: "date" with a nested date object:

For dateResolution: "day", use UTC midnight ISO strings (e.g. 2025-05-19T00:00:00.000Z) for start and end. Other values are rejected with cap_invalid_input and a message showing the expected canonical form.

"dueDate": {
  "type": "date",
  "date": {
    "dateResolution": "day",
    "start": "2025-05-19T00:00:00.000Z",
    "end": null
  }
}

Tags and object select (entity)

Entity properties link an object to other objects in the same space — by reference, not by copying their data. In the API they always use type: "entity" and an entity array of { "id": "…" } objects. The API does not use { id, structureId } pairs in property payloads; only the target object id is required.

This covers:

• Tags — the built-in tags field on pages, tasks, media, and many other types (type: "entity" in the API).
• Object select — custom relation fields on object types you define in Capacities (internal type entity), for example “Related pages” or “Author”.

These are different from label properties (Labels), which pick from a fixed option list on the structure, not from separate objects.

Tags

On most structures, the property id is tags. Each entry points at a tag object (structureId: "RootTag"). Tags are normal objects: they have a title and can be created, read, and updated like pages or tasks.

"tags": {
  "type": "entity",
  "entity": [
    { "id": "a793dc41-a1c1-4f38-836e-6527e5a8c016" },
    { "id": "b804ed52-b2d2-4f49-947f-7638e6b9d127" }
  ]
}

To use a tag that does not exist yet, create it first with POST /object and structureId: "RootTag", then reference its id when setting tags on another object.

Object select (custom relations)

Custom object types can define object select properties (shown as type: "entity" on GET /space/structures). Each field only accepts targets whose structure is allowed for that property in the Capacities app — for example pages only, or a specific custom type. If you pass an id for the wrong type or from another space, the API returns cap_invalid_input.

Use the property definition id from GET /space/structures as the key in properties, the same as for tags.

Reading values on objects

On GET /object, entity properties return only linked object ids (no titles or types inlined):

"tags": {
  "type": "entity",
  "entity": [{ "id": "a793dc41-a1c1-4f38-836e-6527e5a8c016" }]
}

An empty entity array means no links are set. Fetch linked objects with separate GET /object calls if you need titles or other fields.

Writing values

Set or replace links on POST /object or PATCH /object with the same shape. The list you send replaces the current links for that property (it is not merged).

{
  "properties": {
    "tags": {
      "type": "entity",
      "entity": [
        { "id": "a793dc41-a1c1-4f38-836e-6527e5a8c016" }
      ]
    }
  }
}

• Every id must refer to an object that exists in the token’s space.
• Each target’s structureId must be allowed for that property (for tags, only RootTag).
• Pass "entity": [] to remove all links.
• Unknown ids, wrong structure, or objects in another space return cap_invalid_input.

On patch, include only property keys you want to change; omit tags (or other entity fields) to leave them unchanged.

Labels

Label properties are single- or multi-select fields with a fixed option list defined on the structure (for example task status, or a custom “Priority” field on an object type). They are not the same as tags (entity / RootTag links).

Option catalog (labelSet)

On GET /space/structures, every property with type: "label" includes a labelSet array:

{
  "id": "status",
  "name": "Status",
  "type": "label",
  "writable": true,
  "multiple": false,
  "labelSet": [
    { "id": "not-started", "name": "Not started" },
    { "id": "in-progress", "name": "In progress", "color": "blue" },
    { "id": "done", "name": "Done", "color": "green" }
  ]
}

Each entry has:

For task status (RootTask, property id status), labelSet reflects your space’s customized status labels when configured; otherwise you get the default task statuses.

Reading values on objects

On GET /object, selected options use the same id / name / color shape inside a label array:

"status": {
  "type": "label",
  "label": [{ "id": "in-progress", "name": "In progress", "color": "blue" }]
}

An empty label array means nothing is selected.

Writing values

Use the property definition id as the key and reference options by id only (from labelSet or from a prior GET /object). name and color on write are ignored.

{
  "properties": {
    "status": {
      "type": "label",
      "label": [{ "id": "in-progress" }]
    }
  }
}

• Check multiple on the property definition: when false, pass at most one option in label; more than one returns cap_invalid_input.
• When multiple is true, pass several ids in label.
• Pass "label": [] to clear the field.
• Unknown option ids return cap_invalid_input.

Caching definitions

See Objects for how properties fit into full object responses together with collections and blocks.