Handbook Endpoints

The Handbook endpoints let you discover the handbooks a user can access and browse a handbook's structure. As with search, user context must be provided through the X-User or X-SasKey header so that only content the user is permitted to see is returned.

For practical testing of these endpoints, please refer to our Swagger documentation.

List handbooks

GET /api/v1/handbooks

Returns the handbooks the calling user has access to.

Request Parameters

Parameter	Type	Required
`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 array of the handbooks available to the user. An empty array is returned when the user has access to no handbooks.

Response Example

[
    { "id": 100020, "name": "HR Handbook", "description": "Personnel handbook" },
    { "id": 100045, "name": "HSE Handbook", "description": "" }
]

Key Response Attributes

id: Identifier of the handbook. This is the same id used as handbookId in the search endpoint and as the path id for the handbook tree below.
name: Name of the handbook in the requested culture.
description: Description of the handbook, when available.

Handbook tree

GET /api/v1/handbooks/{id}/tree

Returns the full navigation tree (folders, articles and links) of a single handbook.

Request Parameters

Parameter	Type	Required
`id` (path)	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. If the handbook does not exist, or the user has no access to it, the endpoint returns 404 Not Found.

Content Types Reference

Name	Id
Handbook	2
Folder	4
Article	8
Url	16
File	32
FilePointer	16384

Response Structure

A nested JSON object. The root node is the handbook itself; children contains its folders, articles and links recursively, ordered by ordinal. Leaf nodes have an empty children array.

Response Example

{
    "contextId": 100020,
    "contentId": 5001,
    "guid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": 2,
    "name": "HR Handbook",
    "ordinal": 0,
    "children": [
        {
            "contextId": 100021,
            "contentId": 5002,
            "guid": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
            "type": 4,
            "name": "Policies",
            "ordinal": 0,
            "children": [
                {
                    "contextId": 100028,
                    "contentId": 5003,
                    "guid": "5aebc2d5-7957-44df-a55a-595ffae984da",
                    "type": 8,
                    "name": "Audit Policy",
                    "ordinal": 0,
                    "children": []
                }
            ]
        }
    ]
}

Key Response Attributes

contextId: The node's context id — its position in the handbook hierarchy. Pass this to GET /api/v1/items/context/{contextId} to fetch the underlying item without a separate content-id lookup.
contentId: The content id of the underlying item (stable across all placements). Pass this to GET /api/v1/items/{contentId} to fetch the full item.
guid: Globally unique identifier (UUID) of the content item.
type: Content type of the node (see the Content Types Reference above).
name: Name or title of the node in the requested culture.
ordinal: Sort order of the node among its siblings.
children: Array of child nodes with the same structure; empty for leaf nodes.