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​

Your Personal Access Token is a personal unique token, that can be used to securely access the API without needing a username and password. The token looks something like: vktrpat_●●●●●●●●●●●●●●_●●●●●●●●●●●●●●●●●●●●●●●●●● and you can obtain it through your profile settings page.

Storing your Personal Access Token

Your Personal Access Token can be used to access or alter your sensitive data. You should therefore make sure to securely store it and never store it directly in source-code or other plain text formats. Consider using Environment variables.

  1. Set your Personal Access Token as an Environment variable.
  2. Use your token in the Authorization header to perform API requests.
import requests
import os

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

# To never expose your token in code, set your actual token as an environment variable or use `input()` and paste the token in the terminal
token = os.environ["my_token"]  # Must be set as environment variable

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

# Print the response
print(response.json())

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.