> For the complete documentation index, see [llms.txt](https://docs.qvantum-plan.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qvantum-plan.de/dev/general-information.md).

# General Information

This page lists information to access the API that is relevant for all endpoints.

## Authentication

Authentication in QVANTUM relies upon the [OpenID Connect](https://openid.net/connect/) protocol, being a simple identity layer on top of the [OAuth 2.0](https://oauth.net/2/) protocol. For third-party client authentication with the QVANTUM Public API, we particularly employ the [OAuth 2.0 Password Grant](https://oauth.net/2/grant-types/password/). A valid access token is prerequisite to any use of the QVANTUM Public API. Such a token can be acquired in exchange for a set of credentials valid within the tenant context. The respective authentication request includes details such as tenant id, client id, credentials, and a fixed grant type.

**Authentication Request with curl**

```sh
curl --request POST \
  --header "Content-Type:application/x-www-form-urlencoded" \
  --data "grant_type=password" \
  --data "client_id=${CLIENTID}" \
  --data "username=${USERNAME}" \
  --data "password=${PASSWORD}" \
  "${AUTH}/auth/realms/${TENANT}/protocol/openid-connect/token"
```

In case of a successful authentication, the response body will include a JSON payload like the following. Most importantly, the payload includes an access token, which will be required in all subsequent calls to the QVANTUM Public API. For the rest of this tutorial, the environment variable `TOKEN` represents the value for a valid access token gathered by this initial request. By default, all access tokens will expire after 5 minutes. For refreshing an access token, the response also includes a refresh token, expiring after 30 minutes.

**Authentication Response JSON Payload**

```json
{
  "access_token": "<TOKEN>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "7f97c7ba-aac8-4a26-854b-ecd833b67ac3",
  "scope": "profile email add_audience_plankit-service"
}
```

For all subsequent requests to the QVANTUM Public API, access token information is passed as `Authorization` header with value `Bearer ${TOKEN}`.

## Navigation

The QVANTUM Public API is designed as a REST-style API following the [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) principle. As such, endpoints represent *resources* relevant in a planning domain. Besides resource-specific information, each resource also includes a set of *links* to itself and other resources, thus allowing navigation by following links in series of requests. Every navigation starts with the tenant collection as an entry point. Next, link relations are followed to the relevant resources (e. g. plans or cubes). Navigation to further resources not explicitly documented here follows the same principle.

{% hint style="warning" %}
Clients using the QVANTUM API **must** use navigations via link since URLs can change at any time. Only the entry point URL `${API}/api/v1/tenants` is guaranteed to stay the same. The name of the links in the resources will not be changed or removed, therefore allowing for backward compatibility with older clients. If a client does not use navigation via links it may break at any time!
{% endhint %}

### Navigating to a Tenant

With the availability of an access token, navigation starts with a request to the tenants resource, representing the list of all available tenant resources. The access token is passed via an authentication header `Authorization` with value `Bearer ${TOKEN}`, acquired during [authentication](#authentication).

**Retrieve Tenant Information**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants'
```

The response payload includes a JSON representation of a one-element list of tenant representations. Besides an id, display name, and description, a tenant resource includes the following links:

* `allPlans`: a link to a collection of all plan resources
* `plans`: an array of links to the plan resources.
* `allUsers`: retrieval link for user definition (cf. [retrieve user definition](/dev/team.md#retrieve-user-definition))
* `userUploads`: upload link for user definition (cf. [upload user definition](/dev/team.md#upload-user-definition))
* `planning-app`: link to planning web application

**Tenant JSON Representation**

```json
{
  "tenants":[
    {
      "id":1,
      "displayName":"My Tenant",
      "description":"A tenant for me.",
      "_links":{
        "self": {
          "href":"https://api.qvantum-plan.de/api/1/tenants/1"
        },
        "allPlans":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans"
        },
        "plans":[
          {
            "href":"https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
          }
        ],
        "allUsers":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/users{?includeControllers}",
          "templated": true
        },
        "userUploads":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/userUploads"
        },
        "planning-app":{
          "href":"https://app.qvantum-plan.de/thinking-networks/"
        }
      }
    }
  ]
}
```

### Navigating to a Plan

Within a tenant, QVANTUM supports a collection of plans. The `allPlans` link will return this collection. Alternatively, starting from a tenant resource, following a link in the `plans` array provides a shortcut to the URL of the plan resource. A request to this resource provides information about the respective planning application, including further navigation links.

**Retrieve Plan Information**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  '${PLAN_LINK}'
```

The response payload includes a JSON representation of the plan resource. Besides an id, title, status and end date, a plan resource includes the following links:

* `owner`: owning tenant
* `uploads`: endpoint for planning model metadata (cf. [upload planning model](/dev/model.md#upload-planning-model)).
* `allCubes`: list of all cube resources within this plan
* `allStructures`: list of all structure resources within this plan
* `allPermissions`: upload resp. retrieval link for permission assignment (cf. [upload permission assignment](/dev/team.md#upload-permission-assignment) resp. [retrieve permission assignment](/dev/team.md#retrieve-permission-assignment))
* `structuresUploads`: endpoint can be used to update structures
* `userStates`: an array of links to the state of each planner in this plan (cf. [planner status](/dev/update_workflow.md#planner-status))

The states of all planners are also embedded in the plan resource, so that a single request is sufficient to see who is still working on the plan.

The "status" field may have only these values:

* `NOT_STARTED` : the workflow has not been started yet.
* `RUNNING` : the workflow is running.
* `PAUSED` : the workflow has been paused.
* `FINISHED`: the workflow has been finished.
* `EXPORTED`: the workflow has been finished and the data has been exported.

Updates of `title`, `endDate` and `status` can be updated with a PATCH request (cf. [Updating a Plan](/dev/update_workflow.md#plan-status)).

### Plan JSON Representation

```json
{
  "id": 1,
  "title": "My Plan",
  "endDate": "2022-09-30T21:59:59Z",
  "status": "<WORKFLOW_STATUS>",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
    },
    "owner":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1"
    },
    "uploads":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/modelUploads?planId=1"
    },
     "allStructures": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures?planId=1"
    },
    "allCubes":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes?planId=1"
    },
    "allPermissions": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/permissions?planId=1"
    },
    "structuresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structuresUploads?planId=1"
    },
    "userStates": [
      {
        "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/userStates/2"
      }
    ]
  },
  "_embedded": {
    "userStates": [
      {
        "status": "SUBMITTED",
        "submissionDate": "2022-09-28T14:21:07Z",
        "sessions": {
          "f0f7d13e-9d3d-4b3f-8ba1-59ee89b2d76e": {
            "lastOnline": "2022-09-28T14:20:53Z",
            "unsavedChanges": false
          }
        },
        "_links": {
          "self": {
            "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1/userStates/2"
          },
          "plan": {
            "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
          },
          "user": {
            "href": "https://api.qvantum-plan.de/api/v1/tenants/1/users/2"
          }
        }
      }
    ]
  }
}
```

### Navigating to a Cube

Within a plan, QVANTUM supports a set of cubes. As for plans within tenants, this set is currently limited to one cube per plan. Starting from a plan resource, following the link `allCubes` leads to a cube collection resource, listing all available cubes.

{% tabs %}
{% tab title="Retrieve Cube List" %}

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${ALL_CUBES_LINK}'
```

{% endtab %}

{% tab title="Retrieve Single Cube" %}

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${CUBE_LINK}'
```

{% endtab %}
{% endtabs %}

The response payload includes a JSON representation of a one-element array of cube representations. Besides an id, business key, display name, and description, each cube representation includes the following links:

* `dimensions`: array of links to this cube's dimension resources.
* `keyFigures`: export link for the key figures (cf. [export key figures](/dev/key-figures.md#export))
* `keyFiguresUploads`: upload link for the key figures (cf. [upload key figures](/dev/key-figures.md#upload))
* `dataUploads`: upload link for cube cell data (cf. [upload initial data](/dev/cell-data.md#upload-initial-data))
* `dataDeletions`: link for cell data deletions (cf. [deleting planning data](/dev/cell-data.md#deleting-planning-data))
* `data`: download link for cube cell data (cf. [export cell data](/dev/cell-data.md#exporting-planning-data) / [delete cell data](/dev/cell-data.md#deleting-planning-data))
* `changelog`: download link for the changelog of the cube's cell data (cf. [export the changelog](/dev/cell-data.md#exporting-the-changelog))
* `template`: download link to cube cell data template (cf. [download data template](/dev/cell-data.md#download-data-template))
* `modelUploads`: upload link for full model updates (cf. [upload full model update](/dev/model.md#upload-full-model-update))
* `allExternalForms`: import/export link for forms (cf. [export](/dev/forms.md#folders-and-forms-export) and [import](/dev/forms.md#folders-and-forms-import) of forms)

**Single Cube JSON Representation**

```json
{
  "id": 1,
  "businessKey": "MYCUBE",
  "displayName": "My Cube",
  "description": "A cube for me.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1"
    },
    "plan":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plans/1"
    },
    "dimensions":[
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/2"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/3"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/4"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/5"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/6"}
    ],
    "keyFigures": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/keyFigures"
    },
    "keyFiguresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/keyFiguresUploads?cubeId=1"
    },
    "dataUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/dataUploads?cubeId=1"
    },
    "dataDeletions": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/dataDeletions?cubeId=1"
    },
    "data":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/cells{?dimensionRestrictions,inputAllowedFilter}"
    },
    "changelog":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/changelog"
    },
    "template":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/template"
    },
    "modelUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/modelUpdates?cubeId=1"
    },
    "allExternalForms": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/forms"
    }
  }
}
```

### Navigating to a Dimension

A cube is substantial part of the model behind a plan. A cube mainly consists of a set of dimensions. Detailed information on the structure of a planning model is available in section [Planning model definition](/dev/model.md#planning-model-definition).

Starting from a cube, following one of the `dimension` links leads to a dimension resource.

**Retrieve Single Dimension**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${DIMENSION_LINK}"
```

The response payload includes a JSON representation of a single dimension. Besides an id, business key, and description, each dimension representation includes singular and plural labels (`singularName`, `pluralName`) and a link `structure` enabling the navigation to the structure, defining the elements of a dimension (cf. next section).

**Single Dimension JSON Representation**

```json
{
  "id": 1,
  "businessKey": "KF",
  "singularName": "Key Figure",
  "pluralName": "Key Figures",
  "description": "A dimension for key figures.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/cubes/1/dimensions/1"
    },
    "cube":{
      "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/cubes/1"
    },
    "structure":{
        "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/structures/1"
    }
  }
}
```

### Navigating to all Structures

Within a plan, QVANTUM supports a set of structures. Starting from a plan resource, following the link 'allStructures' leads to a structure collection resource, listing all available structures with their elements as described [here](/dev/model.md#upload-more-than-one-structure).

**Structure List**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  --header "Accept:application/x.de.qvantum-plan.external-structures+json" \
  '${ALL_STRUCTURES_LINK}'
```

### Navigating to a Structure

Conceptually, each dimension is defined by an underlying structure and its elements.

Starting from a dimension, following the `structure` link leads to a structure resource.

**Retrieve Single Structure**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  ${STRUCTURE_LINK}"
```

The response payload includes a JSON representation of a structure. Besides an id, business key, display name, description and further properties, each structure representation includes a link `upload`, allowing the upload of updates, in particular updates on the structure and the dimension based on it (cf. [updating planning models](/dev/model.md#updating-planning-models)).

**Structure JSON Representation (extract)**

```json
{
  "id": 1,
  "businessKey": "COSTCENTERS",
  "displayName": "Cost Centers",
  "description": "A structure defining a set of cost centers",
  ...
  "customAttributes": [
    {
      "businessKey": "COSTCENTERCLASS",
      "displayName": "Cost Center Class",
      "description": "Attribute to document different classes of cost centers",
      "attributeType": "TEXT"
    }
  ],
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structures/1"
    },
    "plan":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/plan/1"
    },
    "upload": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/structureUploads?structureId=1"
    }
    ...
  }
}
```

## Localization

Some endpoints deliver localizable texts, e.g. log entries when [uploading planning models](/dev/model.md#upload-planning-model). The desired locale can be specified using the `Accept-Language` header. Supported locales are `en`, `de` (default) and `de-CH`.

**Specifying Locale in Request**

```sh
curl --show-headers --request GET \
  --header "Authorization:Bearer ${TOKEN}" \ 
  --header "Accept-Language:en"
  "${MODEL_UPLOAD_LINK}"
```