This article explains how to retrieve Guides and Pages from the Deskpro API. It is intended for developers integrating with Deskpro who want to read guide content programmatically.

You will learn how to:

• Authenticate with the Deskpro API

• Retrieve a single guide by ID

• Retrieve all topics for a guide in one request

• Retrieve the topic hierarchy (tree)

• Combine endpoints to retrieve a guide with all of its content

Getting Started

Prerequisites

Before you begin, you’ll need:

• Your Deskpro helpdesk domain
  (e.g. https://support.example.com)

• A Deskpro API key with permission to read guides and topics

• Basic familiarity with HTTP requests

Authentication

Deskpro uses API keys for authentication.

All requests must include the following headers:

Authorization: key 1:ABC123DEF456
Accept: application/json

Replace 1:ABC123DEF456 with your actual API key.

Base URL

All examples below assume this base URL:

https://<your-deskpro-domain>

1. Retrieve a single guide by ID

Use this endpoint to fetch guide metadata, such as its title and description.

Endpoint

GET /api/v2/guides/{guideId}

Example (curl)

curl -X GET "https://<your-deskpro-domain>/api/v2/guides/12"   -H "Accept: application/json"   -H "Authorization: key 1:ABC123DEF456"

Example (Python)

import requests

BASE_URL = "https://<your-deskpro-domain>"
API_KEY = "1:ABC123DEF456"

response = requests.get(
    f"{BASE_URL}/api/v2/guides/12",
    headers={
        "Accept": "application/json",
        "Authorization": f"key {API_KEY}",
    },
    timeout=30,
)

response.raise_for_status()
guide = response.json()
print(guide)

Example (JavaScript)

const response = await fetch(
  "https://<your-deskpro-domain>/api/v2/guides/12",
  {
    headers: {
      "Accept": "application/json",
      "Authorization": "key 1:ABC123DEF456",
    },
  }
);

if (!response.ok) {
  throw new Error(`Failed to fetch guide: ${response.status}`);
}

const guide = await response.json();
console.log(guide);

2. Retrieve all topics for a guide (recommended)

If your goal is to retrieve all topics belonging to a guide, this is the
simplest and most efficient approach.

Endpoint

GET /api/v2/topics?guide={guideId}

What this returns

• All topics for the specified guide

• Container topics and content topics

• Topic metadata and content (depending on permissions)

• Returned as a flat list (not hierarchical)

This endpoint is ideal for:

• Content exports

• Synchronisation jobs

• Search indexing

• Bulk processing

Example (curl)

curl -X GET "https://<your-deskpro-domain>/api/v2/topics?guide=12"   -H "Accept: application/json"   -H "Authorization: key 1:ABC123DEF456"

Example (Python)

import requests

BASE_URL = "https://<your-deskpro-domain>"
API_KEY = "1:ABC123DEF456"

response = requests.get(
    f"{BASE_URL}/api/v2/topics",
    headers={
        "Accept": "application/json",
        "Authorization": f"key {API_KEY}",
    },
    params={"guide": 12},
    timeout=30,
)

response.raise_for_status()
topics = response.json()
print(topics)

Example (JavaScript)

const url = new URL("https://<your-deskpro-domain>/api/v2/topics");
url.searchParams.set("guide", 12);

const response = await fetch(url, {
  headers: {
    "Accept": "application/json",
    "Authorization": "key 1:ABC123DEF456",
  },
});

if (!response.ok) {
  throw new Error(`Failed to fetch topics: ${response.status}`);
}

const topics = await response.json();
console.log(topics);

3. Retrieve the topic hierarchy (tree structure)

If you need the parent/child structure of topics (for example, to build
navigation menus or breadcrumbs), use the guide tree endpoint.

Endpoint

GET /api/v2/guides/{guideId}/tree

What this returns

• All topics in the guide

• Hierarchical (nested) structure

• Ordering and parent/child relationships

This endpoint focuses on structure, not bulk content export.

Example (curl)

curl -X GET "https://<your-deskpro-domain>/api/v2/guides/12/tree"   -H "Accept: application/json"   -H "Authorization: key 1:ABC123DEF456"

4. Retrieve a guide with all of its content

There is no single API endpoint that returns:

• Guide metadata

• All topic content

• Full topic hierarchy

in one response.

Instead, use the following recommended pattern.

Recommended approach

1. Retrieve the guide

   GET /api/v2/guides/{guideId}
   

2. Retrieve all topics (content)

   GET /api/v2/topics?guide={guideId}
   

3. (Optional) Retrieve the topic hierarchy (structure)

   GET /api/v2/guides/{guideId}/tree
   

Why this works

• /api/v2/topics?guide={id} gives you all topic content in one call

• /api/v2/guides/{id}/tree provides navigation and structure

• Topic IDs can be matched between responses if needed

Choosing the right endpoint