Items

An item is a concrete piece of knowledge under a topic: a process, a policy, or a fact. To find items, read a topic’s items or use search. Reading an item needs the item.read permission, which every role has except external; an external account gets 403, as it does in the app.

Get an item

GET /v1/items/{id}

Returns the item, its nested child items, and the evidence backing it: verbatim quotes, video timestamps or document character ranges, a confidence score, and links to the original content.

Query parameters

Parameter	Type	Notes
`includeHistory`	boolean	Include archived and superseded records.

Request

curl "https://api.mereon.ai/v1/items/itm_2c8b" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "id": "itm_2c8b...",
  "topicId": "top_9f2a...",
  "type": "process",
  "title": "Approve an expense over $500",
  "body": "Expenses over $500 require sign-off from the cost-center manager...",
  "parentItemId": null,
  "status": "ACTIVE",
  "supersededById": null,
  "url": "https://mereon.ai/items/itm_2c8b",
  "createdAt": "2026-01-12T09:05:00.000Z",
  "updatedAt": "2026-05-30T16:25:00.000Z",
  "children": [],
  "evidence": [
    {
      "id": "evd_77aa...",
      "contentId": "cnt_44de...",
      "contentTitle": "Finance Handbook",
      "contentType": "document",
      "quote": "Any expense above $500 must be approved by the cost-center manager.",
      "startTime": null,
      "endTime": null,
      "charStart": null,
      "charEnd": null,
      "confidence": 0.94,
      "url": "https://mereon.ai/content/finance-handbook#10422"
    }
  ]
}

Item fields

Field	Type	Notes
`id`	string	Item id.
`topicId`	string	The topic this item belongs to.
`type`	string	Item kind, for example `process`, `policy`, `fact`. Open set.
`title`	string	Item title.
`body`	string \| null	Full text of the item, when present.
`parentItemId`	string \| null	Parent item, when this is a sub-step.
`children`	Item[]	Nested child items, same shape.
`evidence`	Evidence[]	Source evidence. Present on this detail endpoint.

Evidence fields

Field	Type	Notes
`contentId`	string	The source content this evidence comes from.
`contentTitle`	string \| null	Title of the source content.
`contentType`	string \| null	For example `document` or `video`.
`quote`	string \| null	Verbatim quote from the source, when captured.
`startTime` `endTime`	number \| null	Time range in milliseconds from the start of the source, for video and audio sources.
`charStart` `charEnd`	number \| null	Always `null`. Document evidence is recorded against the section it came from rather than the whole document, so there is no document-wide range to report. Use `quote` to find the passage.
`confidence`	number	Extraction confidence, 0 to 1.
`url`	string	Deep link to the source location.

Retiring an item

Retiring an item withdraws one fact the organization no longer follows. The topic continues. Lessons that teach that topic stay open and cover one fact less. Child items go with the item. The videos and documents stay in the library. Required training aimed at the item is cancelled, and a restore does not put it back.

These routes need item:retire and permission to retire items, which owners and admins have. Reading an item stays on read. Retiring the whole topic is topic:retire. An item you cannot read is 404. There is no choice about people part-way through a lesson, because no lesson closes.

Preview retiring an item

GET /v1/items/{id}/retirement/preview

What retiring this item would withdraw. Writes nothing. childItemCount is how many child items go with it. lessonsNarrowingIds are lessons that keep teaching the topic.

curl "https://api.mereon.ai/v1/items/itm_2c8b/retirement/preview" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Retire an item

POST /v1/items/{id}/retirement

Withdraws the item. reason is optional, up to 2,000 characters. A body that names what should happen to people part-way through a lesson is refused, because this retirement closes none. Returns the retirement, 201.

curl -X POST "https://api.mereon.ai/v1/items/itm_2c8b/retirement" \
  -H "Authorization: Bearer $MEREON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "We no longer do this step" }'

Restore a retired item

DELETE /v1/items/{id}/retirement

Brings a retired item back, and the child items that retirement archived, each to the status it held. Required training the retirement cancelled is not brought back. Returns the retirement that was restored, 200.

curl -X DELETE "https://api.mereon.ai/v1/items/itm_2c8b/retirement" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Status	When
`403`	The token lacks `item:retire`, or the caller may not retire items.
`404`	The item is missing, in another organization, unreadable, or not currently retired on a restore.
`409`	The item is already retired, is not active, its topic is already retired, or its topic is still retired on a restore.
`429`	More than 10 calls a minute or 60 an hour on that route.