Item Endpoint

The Item endpoint returns a single content item of any type by its id or GUID. Like Pithos itself, the endpoint is generic: every item shares a common envelope, and the item payload is composed according to the item's contentType. A consumer uses one endpoint for everything and branches on contentType.

As with the other endpoints, user context must be supplied through the X-User or X-SasKey header so that only content the user may access is returned.

For practical testing of this endpoint, please refer to our Swagger documentation.

An item can be fetched in three ways:

GET /api/v1/items/{guid} — look up by content GUID. This is the guid returned for each hit by the search endpoint.
GET /api/v1/items/{contentId} — look up by numeric content id. This is the id returned for each hit by the search endpoint, and the contentId of any node in the handbook tree.
GET /api/v1/items/context/{contextId} — look up by numeric context id (the id of a specific placement of the item inside a handbook tree). This is the contextId of any node in the handbook tree, and lets you go straight from a tree node to the item without a separate content-id lookup.

All three forms take the same headers and return the same structure. If the item does not exist, or the user has no access to it, the endpoint returns 404 Not Found.

The numeric `contentId` and `contextId` are different. A piece of content has one stable `contentId`,

and one contextId per placement in a handbook (the same article placed in two handbooks shares one contentId and has two distinct contextIds). The handbook tree returns both for each node so you can choose whichever id is more convenient.

Contract Specification

Request Parameters

Parameter	Type	Required
`guid` / `contentId` / `contextId` (path)	GUID or Integer	Yes
`X-User` (header)	GUID	Yes/No
`X-SasKey` (header)	GUID	Yes/No
`X-Culture` (header)	String: "en-US", "nb-NO", "sv-SE", "EN"	Yes

One of X-User or X-SasKey is required.

Response Structure

A JSON object with a common envelope plus a type-specific item:

Attribute	Description
`id`	Numeric content id of the item (stable across all placements). Pass straight back to `GET /api/v1/items/{contentId}`.
`guid`	Globally unique identifier (UUID) of the content item.
`handbookId`	Identifier of the handbook the item belongs to.
`name`	Name or title of the item in the requested culture.
`description`	Short description of the item, when available.
`contentType`	The item's numeric content type (see table below). Always present — branch on this.
`item`	Type-specific payload (see below). `null` for types that carry no extra data.

Content Types

`contentType`	Type	`item` payload
`8`	Article	`{ "body": "<html…>" }` — the article content composed into a single HTML string.
`16`	Url	`{ "url": "https://…" }` — the link target.
`32`	File	`{ "fileName": "report.pdf" }` — the file name.
`16384`	FilePointer	`{ "fileName": "linked.docx" }` — same payload as File.
`4`	Folder	`null` — folders carry no extra data; use the handbook tree to list their contents.
other	—	`null` — only the envelope fields are returned.

Response Example (article)

{
    "id": 100028,
    "guid": "5aebc2d5-7957-44df-a55a-595ffae984da",
    "handbookId": 100021,
    "name": "Audit Policy",
    "description": "How and when internal audits are performed.",
    "contentType": 8,
    "item": {
        "$type": 8,
        "body": "<h2>Scope</h2><p>Audits run quarterly.</p>"
    }
}

Response Example (url)

{
    "id": 100030,
    "guid": "0b3f1d6e-2b6a-4d5c-9f10-7a2b3c4d5e6f",
    "handbookId": 100021,
    "name": "Simployer",
    "description": "",
    "contentType": 16,
    "item": {
        "$type": 16,
        "url": "https://simployer.com"
    }
}

Response Example (folder)

{
    "id": 100021,
    "guid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "handbookId": 100020,
    "name": "Policies",
    "description": "",
    "contentType": 4,
    "item": null
}

The `$type` inside `item` is the numeric discriminator that identifies which payload shape it is; it

matches the top-level contentType for the composed types (8 = article, 16 = url, 32 = file).