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.

String fields are always present, and an absent or blank value comes back as an empty string

("") — never null and never omitted. That covers name, description and every string inside item (body, url, urlDescription, folderDescription, fileName). item itself is the only field that can be null, so it is the only one worth a null check.

Because of this, an empty urlDescription or folderDescription does not tell you whether the description is blank in the handbook or absent from the item altogether — treat both as "no description".

Content Types

`contentType`	Type	`item` payload
`8`	Article	`{ "body": "<html…>" }` — the article content composed into a single HTML string.
`16`	Url	`{ "url": "https://…", "urlDescription": "…" }` — the link target and its description, when the link has one.
`32`	File	`{ "fileName": "report.pdf" }` — the file name.
`16384`	FilePointer	`{ "fileName": "linked.docx" }` — same payload as File.
`4`	Folder	`{ "folderDescription": "…" }` — the folder description, when it has one. Use the handbook tree to list a folder's 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",
        "urlDescription": "Our website"
    }
}

Response Example (folder)

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

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

matches the top-level contentType for every composed type (4 = folder, 8 = article, 16 = url, 32 = file, 16384 = file pointer).