Slot roles

A slot is a named part of a piece — steps, before, summary. A role says what that part is FOR, from a controlled vocabulary of six words.

This is the thing you cannot get from a documentation platform whose content is markdown with a title: there is nowhere to hang meaning, so retrieval is left to whoever is embedding it, and that party is guessing.

The vocabulary

GET /api/roles

{
  "version": "2026-09-01",
  "roles": [
    { "id": "summary",      "order": 0, "gloss": "What this is, in one paragraph." },
    { "id": "symptom",      "order": 1, "gloss": "How the reader knows they are in the right place." },
    { "id": "prerequisite", "order": 2, "gloss": "What must be true before the steps will work." },
    { "id": "resolution",   "order": 3, "gloss": "The part that changes something. The answer." },
    { "id": "example",      "order": 4, "gloss": "A worked instance of the above." },
    { "id": "reference",    "order": 5, "gloss": "Lookup material. Not read start to end." }
  ],
  "unroledPolicy": "inherit-previous"
}

order is the canonical reading position. It is ours to state and yours to rely on: an integrator who invents their own ordering gets a different article out of the same content, and the day a seventh role appears their ordering degrades with nothing anywhere erroring.

Slots with no role

Not every slot is one of the six, and a slot that is none of them says so by carrying no role at all. inherit-previous: an unroled slot takes the rank of the last roled slot before it. So "How to tell it worked", sitting after the steps, stays with the steps instead of drifting to the end.

It is not customisable per space

Deliberately. The moment the vocabulary varies per customer it stops being a contract, and every integrator goes back to ignoring it. A space that needs its own idea of a slot has label, which is free text — and its own kinds, which are anything it likes.

Where to read a space's slots

GET /api/orgs/{orgId}/spaces/{spaceId}/shape — shape.sections for what a piece here is made of, and presets[].sections for each kind of piece the space offers, each slot with its key, label, whether it is required, and its role.