Skip to main content

SDK API

The VIKTOR SDK API can be accessed using the api_v1 module and is built on top of the REST API. It provides access to many of the relevant requests through an even developer-friendlier Python interface and 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.

Authentication​

It is possible to use the SDK API in 3 scenarios:

  • Within a workspace (nothing needed)
  • Cross-workspace (token needed)
  • From an external script (token and environment needed).

Within a workspace​

If you want to use the SDK API module from within the context of a workspace, it is as simple as instantiating the API class using VIKTOR's api_v1 module:

from viktor.api_v1 import API

api = API()
...
entity = api.get_entity(1)

Cross-workspace​

If you want to use the SDK API module from one workspace to access data from a different workspace, you can instantiate the API class using VIKTOR's api_v1 module and include your Personal Access Token (personal unique token to access the API; you can obtain it through your profile settings page):

from viktor.api_v1 import API

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

From an external script​

If you want to use the SDK API from an external python script (e.g. Jupyter Notebook), make sure to first install the VIKTOR SDK using pip:

pip install viktor

In your python script, you can now instantiate the API class using VIKTOR's api_v1 module. You will need to provide some additional authentication-related information:

  • Your VIKTOR environment url (the location where your data is stored, e.g. cloud.viktor.ai or company.us1.viktor.ai)

  • Your Personal Access Token (personal unique token to access the API; 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.

from viktor.api_v1 import API

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

Scope​

The VIKTOR SDK API provides access to a subset of all REST API resources. The following resources are available in the SDK API:

  • Workspaces
  • Entity types
  • Entities
  • Revisions
  • Current user

How to use?​

For detailed SDK API examples please refer to the upcoming section.