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. 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.

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

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