Items

Create, read, fill and publish a piece in any kind of space through one endpoint, with the shape as JSON Schema.

Embed
Preview of the card
<a href="https://forumulate.com/reference/items"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/9b45c823-03cc-45e5-b0de-fe7f2f9636d8/social-card.svg?v=3e7ae33eec8b" alt="Items" width="600" height="315"></a>

One endpoint writes a piece into any kind of space — a documentation page, a blog post, a forum topic, a roadmap card, a changelog entry, an incident. The space decides what a piece is made of; you post that.

Usage

GET    /api/orgs/{org}/spaces/{space}/shape?preset={kind}
POST   /api/orgs/{org}/spaces/{space}/items
GET    /api/orgs/{org}/spaces/{space}/items
GET    /api/orgs/{org}/spaces/{space}/items/{id}
PUT    /api/orgs/{org}/spaces/{space}/items/{id}/sections/{key}
POST   /api/orgs/{org}/spaces/{space}/items/{id}/publish

Parameters

  • title (string, required) — the piece's title.

  • slug (string) — the address it answers to. Derived from the title when omitted.

  • preset (string) — which kind of piece, from the shape's presets.

  • sections (object) — markdown per declared slot, keyed by the slot's key.

  • body (string) — markdown, for a space whose shape declares no slots.

  • params (object) — the parameters the shape declares (a version, a severity, a cover image).

Returns

Create and publish both return a conformance object naming the required slots still empty. An agent can create a piece, ask what it forgot, and close the gap rather than assuming it got it right.

Examples

curl -X POST -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  https://forumulate.com/api/orgs/$ORG/spaces/$SPACE/items \
  -d '{"title":"Rotate an API key","preset":"how-to","sections":{"goal":"…","steps":"1. …"}}'
The Forumulate teamUpdated
#api