Skip to main content

API

Welcome to the VIKTOR API documentation.

What is an API?

An API, or Application Programming Interface, acts as a communication gateway between different software applications. It defines the rules and tools for building software and allows developers to access the functionality of a system, service, or platform. In simpler terms, an API enables interaction and data exchange between software components.

When to Use?

The API provides a standardized interface to access specific features of the VIKTOR platform. Our API can be used to extract or modify data from your environment, integrate apps into your own software and workflows or automate tasks. When accessing the VIKTOR in the browser, using the API is not required as the functionality is directly available through the user interface.

Authentication

To authenticate with the VIKTOR API, you need to follow a two-step process. First, use Basic Authentication with your username and password, and upon successful authentication, obtain a Bearer token from the response for subsequent secure access to the API.

The example below shows how to obtain the bearer token using your username and password.

import requests

# Replace 'your_username' and 'your_password' with your actual username and password
username = 'your_username'
password = 'your_password'

# Replace 'your_environment' with your actual environment e.g. 'cloud' or 'cloud.us1' if you are in a region other than Frankfurt
environment = 'your_environment'

# Sending a POST request to obtain a Bearer token
response = requests.post(f'https://{environment}.viktor.ai/api/o/token/', data={
"grant_type": "password",
"client_id": "e17LqAF9OGdZ4fVwHdDrpUEYQrWldqNVpvBdS1lb",
"username": username,
"password": password
}
)

# The Bearer token can be obtained from the response body when the request is succesful
if response.status_code == 200:
print(response.json()["access_token"])

The Bearer token should be included in the Authorization header in any subsequent request to access resources through the API:

import requests

# Replace 'your_bearer_token' with your actual Bearer token
bearer_token = 'your_bearer_token'

# Replace 'your_environment' with your actual environment e.g. 'cloud' or 'cloud.us1' if you are in a region other than Frankfurt
environment = 'your_environment'

# Sending a GET request with Bearer token to obtain the list of workspaces in your VIKTOR environment
response = requests.get(f"https://{environment}.viktor.ai/api/workspaces/", headers={'Authorization': f'Bearer {bearer_token}'})

# Print the response
if response.status_code == 200:
print(response.json())
SSO

When your environment has SSO enabled it is not possible to use Basic Authentication to obtain a Bearer token. A temporary workaround is to obtain your Bearer token using the Developer Tools of your browser to inspect a request sent by the VIKTOR frontend and retrieve the Bearer token in that way.

Pagination

When working with large sets of data, efficient handling is crucial. Our API supports pagination, allowing you to retrieve data in manageable chunks. Understand the pagination parameters and techniques to navigate through paginated results effectively, ensuring optimal performance and resource utilization in your applications.

To paginate your results with the VIKTOR API you can add to your request the query params limit and offset.

  • limit is required and is used to specify the number of results you want to retrieve. Note that the results returned might be fewer than requested, depending on the max allowed page size of the resource you are trying to access.
  • offset is optionally used to specify the position of the first result you will receive in the total number of results. If not specified, it defaults to 0, the first result. Note that if the endpoint allows sorting of the results, the offset specifies the position relative to the requested sorting.

For example, if the total number of results is 10 and you want to retrieve them in pages of 5, you can get all the results by sending the 2 requests below:

  • <endpoint>?limit=5&offset=0
  • <endpoint>?limit=5&offset=5

In the paginated response you will receive two keys:

  • count will return an integer with the number of total results
  • results with return a list of objects of the requested resource
Exceptions

The above structure is our go-to way for paginating results, but make sure to check the endpoint specific descriptions for potential exceptions.

How to Use?

For detailed API specifications and endpoints please refer to individual reference pages in the upcoming sections.