Text tokens are the inline pieces that make up formatted text in Capacities. They appear in two places in the API:

• Inside TextBlock blocks — the tokens array on each text block (see Blocks)
• On richText properties — the richText.value array on GET /object (see Properties)

Both use the same token types and shapes.

Token types

Each token has a type field. The payload fields depend on the type:

TextToken

{
  "type": "TextToken",
  "text": "Hello ",
  "style": {
    "bold": true,
    "italic": false,
    "strikethrough": false,
    "underline": false
  }
}

style fields are optional booleans. You may also set color to a theme color key when the app uses colored text.

LinkToken

{
  "type": "LinkToken",
  "text": "Capacities",
  "url": "https://capacities.io"
}

To link to an object in your space, set entityId to that object's id (and usually omit url):

{
  "type": "LinkToken",
  "text": "My page",
  "entityId": "7d2e7f8a-4c3b-4e1d-9f0a-123456789abc"
}

MathToken and CodeToken

{ "type": "MathToken", "text": "E = mc^2" }

{ "type": "CodeToken", "text": "npm install" }

Building a line of text

A TextBlock (or richText property) is a sequence of tokens — like runs in a rich-text editor. Adjacent TextToken spans with different styles sit next to each other:

{
  "type": "TextBlock",
  "tokens": [
    { "type": "TextToken", "text": "Read the ", "style": {} },
    { "type": "LinkToken", "text": "docs", "url": "https://docs.capacities.io" },
    { "type": "TextToken", "text": " for details.", "style": {} }
  ],
  "blocks": [],
  "hierarchy": { "key": "Base", "val": 0 }
}

When writing blocks, you can omit id on the block; the server assigns ids. Tokens do not have their own ids — order in the array is the order on the page.

Markdown alternative

If you do not want to assemble tokens by hand, use the Markdown routes to create or append content; the server converts Markdown into blocks and tokens for you.