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. If you want to exchange data with the VIKTOR platform by means of code you can use the API.

REST API vs SDK

VIKTOR provides both a low-level REST API and an API module as part of the SDK.

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.

The VIKTOR SDK API is built on top of the REST API and provides access to many of the relevant requests through an even developer-friendlier Python interface. The SDK API takes care of more complicated parts such as 'pagination', 'filtering by reference', and 'object serialization'. We therefore strongly recommend using the SDK API wherever possible.

Personal Access Token

When using the SDK API from within the context of a workspace, authentication is done automatically with the token of the current user performing the API call, which is valid within the workspace.

When the SDK API is used cross-workspace or from an external script, or when using the REST API a Personal Access Token needs to be used for proper 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.

By authenticating using a Personal Access Token, you obtain the same rights as the user that holds the token.

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.

SDK

1. Set your Personal Access Token as an environment variable.
2. Create an API instance with your token to perform API requests.

from viktor.api_v1 import API

api = API(token=os.environ["TOKEN"], ...)
...
workspace = api.get_workspace(3)
entity = workspace.get_entity(1)

REST

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())