Skip to main content

REST API

The REST API is the foundation for interaction and data exchange with the VIKTOR platform. Developers can use it to access app or organizational resources through HTTP requests. The REST API is programming-language agnostic and can be accessed by all popular programming languages such as Python, Javascript, Go(lang), Ruby, C#, etc.

Authentication​

REST API calls can be authenticated by using your Personal Access Token in the Authorization header:

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.