# TOPdesk API

Benifit from the data that you already have in your TOPdesk instance when you build AI agents in Ebbot. Note: On this page, standard TOPdesk terminology is sometimes used.

**KB** - TOPdesk Knowledge Base

**KA / KI** - Knowledge Base Articles or Knowledge Items

**SSP** - TOPdesk Self Service Portal

## Activate TOPdesk Knowledge Base API 

Before you're able to access the TOPdesk Knowledge Base APIs, the TOPdesk instance needs to have access to the Knowledge Management API, and a feature flag has to be activated for the TOPdesk environment. For information on how to do this, please visit the links below (My TOPdesk).

### Activate the API on a TOPdesk SaaS instance

[Activate Knowledge Base API Feature Flag](https://my.topdesk.com/tas/public/ssp/content/detail/knowledgeitem?unid=49ae9fd0371245da90217129819d60f4)

[Request access to knowledge base API form](https://my.topdesk.com/tas/public/ssp/content/serviceflow?unid=e15ba8f3be1b4a17a4660b50f1bd5772)

### Activate the API on a TOPdesk on-premise instance

[Activate Knowledge Base API Feature Flag](https://my.topdesk.com/tas/public/ssp/content/detail/knowledgeitem?unid=49ae9fd0371245da90217129819d60f4)

## Connecting your TOPdesk Knowledge Base to EbbotGPT

When the APIs are active and ready to go, it's time to do some initial setup in Ebbot. 

### Initial steps

Go to **EbbotGPT** > **Knowledge** 

Click the tab **Sources** and click the green **Create new!** button on the right side of the page. 

Give the source a name and enter your TOPdesk instance **domain**, the **username** of a user with access to the TOPdesk Knowledge Base, and the user's application password. (See [Password section](#password) below for info on how to obtain this).

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2FzPOMV0jD5Owt47MlSaXZ%2Fimage.png?alt=media&#x26;token=ba35fbf9-8bad-41cb-a82e-c251ba3b69c2" alt=""><figcaption></figcaption></figure>

### Settings

**Full domain**

The full domain for the TOPdesk environment.

**Username**

The username of the TOPdesk operator account you wish to use.

**Password**

The API key you've created for the TOPdesk operator account which can be created by going to "My Settings) (in the TOPdesk operator portal):

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2FdIxfJWQThODTlimcMvGY%2Fimage.png?alt=media&#x26;token=78a19be6-ce06-475d-9d12-9356082b83e5" alt=""><figcaption></figcaption></figure>

Click on "Add", fill out an "Application name", set an expiration date and then click on "Create". **Note!** Make sure to save the application password during this step – it will only be shown once.&#x20;

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2F1Y7ljgNrWXvnjLIdrttG%2Fimage.png?alt=media&#x26;token=e318336a-b509-4fa9-ad6d-294f5c3df00d" alt=""><figcaption></figcaption></figure>

**Send references to the GPT model**

If this setting is enabled, the model will also receive the fields "operatorUrl", "operatorUrl", and the knowledge article "id". Where the idea is that you could prompt the persona to for example say: "\<content>...you can read more here: \<operatorURL>"

### Result after successful scrape

An entry in the source would look like this:

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2FA3ggScYEatskltoweFPX%2Fimage.png?alt=media&#x26;token=d5f7276a-7e30-4278-9528-98ca991e2e96" alt=""><figcaption></figcaption></figure>

## Articles included in the TOPdesk Knowledge Base scrape

Ebbot applies some filtering to the API call fetching the KIs:

```
query=visibility.sspVisibility==VISIBLE;archived==false
```

This means that we are including KIs that are visible in the SSP and not archived.&#x20;

**Example:**&#x20;

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2F54yfovao9U7eTsOqwY46%2Fimage.png?alt=media&#x26;token=d38e940f-bc3d-44c8-8344-28ccf02f7cb3" alt=""><figcaption><p>This article would not be included</p></figcaption></figure>

### Filter articles using query filters

Use TOPdesk filters to filter out (exclude) KIs from being imported into EbbotGPT Knowledge. Read more about TOPdesk filter [here](https://developers.topdesk.com/tutorial.html) under the section FIQL queries.

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2FzoCGRNGkyEVG84Q6EUMl%2Fimage.png?alt=media&#x26;token=3a28664d-9434-4c18-8108-60fdee58d4f7" alt=""><figcaption></figcaption></figure>

### IP / Whitelisting

To ensure the Ebbot Platform can access your TOPdesk environment, please add the following IP address to your firewall whitelist: 141.94.175.178/32.

## Why the TOPdesk Knowledge Base scrape fails

Here, we list some potential reasons why you are not succeeding when trying to connect your KAs from TOPdesk to Ebbot and use them as your knowledge for your AI agents.

### Feature flag not active

This status error message indicates that the feature flag isn't active for KB APIs:

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2F9fd0rHzJpCxOM958gwiR%2Fimage.png?alt=media&#x26;token=420035e7-f4db-4236-91cc-2f24a7dab8a2" alt=""><figcaption></figcaption></figure>

```
{"detail":"Feature flag not active"}
```

### User missing permissions

API user doesn't have access to KB APIs:

<figure><img src="https://2117387010-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rWESGvwA3vHJ3zNiAG1%2Fuploads%2FAXTKbB8kpNttPe6RfjRw%2Fimage.png?alt=media&#x26;token=09f2de9a-912d-4753-88aa-ea8d59c1983d" alt=""><figcaption></figcaption></figure>

To gain access, see the [Activating the API and feature flag in TOPdesk](#activating-the-api-and-feature-flag-in-topdesk) section above.

### Scraper can't reach host

Targeted host had not opened their firewall. IP to whitelist can be found [above](#ip-whitelisting).

{"errno":-110,"code":"ETIMEDOUT","syscall":"connect","address":"143.131.145.133","port":443}, status: undefined, code: ETIMEDOUT, data: undefined


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ebbot.ai/ebbot-docs/core-capabilities/ebbotgpt/ebbotgpt-knowledge/source-types/api-sources/topdesk-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.