> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Prepare REST API access and understand Qbilon data identifiers.

## Available Resources

This documentation is meant as an addition to the [OpenAPI](https://www.openapis.org/) specification that comes with each Qbilon instance reachable via `Documentation → API Documentation` (the specific URL is always `<host>/openapi/index.html`). This is a [Redocly](https://redocly.com/) UI that contains the documentation of all individual endpoints. If you have feedback regarding the API or need help, feel free to [open a ticket](https://share-eu1.hsforms.com/1lTdb5TBpS2K2LYWzk6rLGAeuvv1).

## Introduction

The Qbilon API is a [REST](https://en.wikipedia.org/wiki/REST) API. This document describes how to use the Qbilon API for [reading](https://doc.qbilon.io/12-customizing-qbilon/rest-api/reading-from-qbilon.md), [writing](https://doc.qbilon.io/12-customizing-qbilon/rest-api/writing-to-qbilon.md), [deleting](https://doc.qbilon.io/12-customizing-qbilon/rest-api/deleting-from-qbilon.md), [linking](https://doc.qbilon.io/12-customizing-qbilon/rest-api/linking-in-qbilon.md), [merging](https://doc.qbilon.io/12-customizing-qbilon/rest-api/merging-in-qbilon.md) and what to expect from it. Qbilon provides a dedicated API in order to allow sophisticated read and write access to its data. This is intended for users who want to either automate a data task from outside of Qbilon or who want to use that API from within a [custom task](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/index).

## Authentication

Currently all API endpoints reachable under the path `/apiv1/data` are secured via basic auth, i.e., each request requires an `Authorization` header with the value `Basic <base64 encoded username:password>` . In order to successfully authenticate against the API endpoints you need to have a valid license in place and user roles of `ADMIN` or `ARCHITECT`.

**Example:** Having created a user in Qbilon with username `api-user` and the password `password123`, the string `api-user:password123` has to be encoded into Base64 format, resulting in `YXBpLXVzZXI6cGFzc3dvcmQxMjM=`. For making a request to an endpoint, the `Authorization` header has then the value `Basic YXBpLXVzZXI6cGFzc3dvcmQxMjM=`.

## Multi-Tenancy

Qbilon is per default a multi-tenancy aware application, therefore **all API requests have to be augmented** with the information about which tenant is targeted via the `Qbilon-Tenant` header. The header has to be sent with all requests to the API endpoints in order for them to work correctly.
The value for it can be found out as an admin by going to `Settings → Manage Realm` . The tenant name is then shown in the upper-left corner like this:

![REST API: Multi-Tenancy](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/1ba4db75-d328-4076-bb1b-7441082ab257-image.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=ad4bb6da0148199482ed3c4242aa6ca5)

Usually it is the same value as your subdomain, e.g., if your Qbilon instance is reachable under `https://nightly.my-company.com` then the value for this header and respectively the tenant would be nightly.

## Qbilon ID vs. External ID

In the examples mentioned for using the API for [reading](https://doc.qbilon.io/12-customizing-qbilon/rest-api/reading-from-qbilon.md), [writing](https://doc.qbilon.io/12-customizing-qbilon/rest-api/writing-to-qbilon.md), [deleting](https://doc.qbilon.io/12-customizing-qbilon/rest-api/deleting-from-qbilon.md), [linking](https://doc.qbilon.io/12-customizing-qbilon/rest-api/linking-in-qbilon.md), [merging](https://doc.qbilon.io/12-customizing-qbilon/rest-api/merging-in-qbilon.md), we only used `externalIds` although there are two different types of IDs in Qbilon, the other one being `qbilonId`. The difference between them is as follows:

* An `externalId` is data source specific, it has only to be unique within the context of the data source/API call that is writing an asset or relation. It can be chosen freely by the author of the data source or the API call. Nevertheless, it must be deterministic: If the same asset "Server 1" is sent twice in two different API calls, then it must have the same ID in both calls.
* A `qbilonId` is globally unique and is assigned by Qbilon when a new asset or relation is written to its database. Later on, this ID can be used by a data source/an API call to directly modify existing assets/relations.
* **Note:** Please note that if both ID types are provided, the `qbilonId` takes precedence without any fallback to `externalId` for `qbilonIds` that have not been found.

## Preparing Data Sources

When data is written to Qbilon, it tracks for each created type/asset/relation and each of their properties which data source wrote the respective data. In addition, Qbilon keeps track of the `First Seen` and `Last Seen` properties for each of them. To be able to do this, all altering actions must be performed in the context of a data source.

Currently, there are three different types of data sources:

* `Manual`: Changes to the data triggered through the UI are tracked via the artificial data source "Manual". It can also be used as a testing data source when using the API via the fixed ID `-2` .
* `System`: "System" is an artificial data source that is used by the application itself when adding data to assets, e.g., the `First Seen` and `Last Seen` properties. It has the fixed ID `-1` and is forbidden to be used within the API. If it is used anyway, Qbilon will return an error response.
* `Task`: Each task in the Qbilon automation engine has a unique ID that can be used as a data source for the writing endpoints. For [custom tasks](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/index), the ID is provisioned as an environment variable.

## URL Encoding

When using URL parameters in API requests, it’s important to know that special characters, such as spaces, percent signs (`%`), slashes (`/`), and parentheses (`–`), require URL encoding to transmit and interpret them correctly. Raw special characters in parameter values can disrupt the parsing of requests by the backend. This can cause parameters to be missed or misread and lead to errors, such as missing required parameters.

To prevent these issues, always encode special characters in parameter values before including them in a URL. For example, the value `Average CPU (%/7d)` should be encoded as `Average%20CPU%20%28%25%2F7d%29`. Standard tools, libraries, and browser APIs provide functions that automatically encode parameters. Proper URL encoding ensures compatibility and reliable data exchange between clients and APIs, especially when values include special symbols or spaces.

## Reading, Writing, Deleting, Linking and Merging

Detailed descriptions of how to use the Qbilon API are available in the sub-chapters:

* [Reading from Qbilon](https://doc.qbilon.io/12-customizing-qbilon/rest-api/reading-from-qbilon.md),
* [Writing to Qbilon](https://doc.qbilon.io/12-customizing-qbilon/rest-api/writing-to-qbilon.md),
* [Deleting from Qbilon](https://doc.qbilon.io/12-customizing-qbilon/rest-api/deleting-from-qbilon.md),
* [Linking in Qbilon](https://doc.qbilon.io/12-customizing-qbilon/rest-api/linking-in-qbilon.md),
* [Merging in Qbilon](https://doc.qbilon.io/12-customizing-qbilon/rest-api/merging-in-qbilon.md),
* [Plain Text Data](https://doc.qbilon.io/12-customizing-qbilon/rest-api/plain-text-data.md) and
* [Schema Data](https://doc.qbilon.io/12-customizing-qbilon/rest-api/schema-data.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.