Skip to main content
Version: 14

viktor.api_v1

API​

class viktor.api_v1.API(environment=None, token=None)

Bases: _API

Starting point of making an API call to, for example, retrieve properties of an entity.

Can be initialized:

  1. within a VIKTOR app, without init-arguments, to perform API calls to any data within the corresponding workspace.

  2. (new in v14.9.0) within a VIKTOR app, with token argument, to perform API calls to any data within the environment (cross-workspace).

  3. (new in v14.9.0) outside a VIKTOR app, with token and environment arguments, to perform API calls to any data within the specified environment.

Note that the permissions of a user (group) are reflected on the permissions of this API call, e.g. if a user only has read-navigate or read-basic permission, calling the params (read-all) of the object using this API will NOT work for this specific user.

Example for case 1 (inside app, within context of current workspace):

api = API()
current_entity = api.get_entity(entity_id)
parent = current_entity.parent()
parent_params = parent.last_saved_params

Example for case 2 (inside app, outside context of current workspace):

api = API(token=os.environ["TOKEN"])
for workspace in api.get_workspaces():
    for entity in workspace.get_root_entities():
        entity_params = entity.last_saved_params

Example for case 3 (external to VIKTOR platform):

from viktor.api_v1 import API

if __name__ == "__main__":
    api = API(token=os.environ["TOKEN"], environment="cloud.us1.viktor.ai")
    for workspace in api.get_workspaces():
        for entity in workspace.get_root_entities():
            entity_params = entity.last_saved_params
get_workspace(id_)

New in v14.9.0

Get the workspace with given id. (Requires a token to be set on the API class)

Parameters:

id – workspace_id

Return type:

Workspace

get_workspaces(*, app_name=None, include_archived=False)

New in v14.9.0

Get the workspaces in the environment. (Requires a token to be set on the API class)

Parameters:

  • app_name (Optional[str]) – Filter the workspaces by app name.

  • include_archived (bool) – True to include the archived workspaces. (Only permitted for Organization Admins)

Return type:

WorkspaceList

Can be used to iterate over the workspaces:

api = API(token=os.environ["TOKEN"])
for workspace in api.get_workspaces():
    for entity in workspace.get_root_entities():
        ...
get_entity_type(id_, *, workspace_id=None)

New in v14.9.0

Get the entity type with given id.

Parameters:

  • id – entity_type_id

  • workspace_id (int) – (optional) Provide workspace id if you want to access entity types outside the context of the app.

Return type:

EntityType

get_entity_types(*, workspace_id=None)

New in v14.9.0

Get the entity types.

Parameters:

workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

Return type:

EntityTypeList

get_entity(id_, *, privileged=False, workspace_id=None)

Get the entity with given id.

Parameters:

  • id – entity_id

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

get_entities_by_type(entity_type_name, *, include_params=True, privileged=False, workspace_id=None)

Get all entities of the given type.

Parameters:

  • entity_type_name (str) – entity type to get all entities for.

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

get_root_entities(*, include_params=True, entity_type_names=None, privileged=False, workspace_id=None)

Get the root entities.

Parameters:

  • include_params (bool) – True to include the parameters of the root entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

get_entity_parent(entity_id, *, privileged=False, workspace_id=None)

Get the parent entity of the entity with given id.

Parameters:

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

get_entity_children(entity_id, *, include_params=True, entity_type_names=None, privileged=False, workspace_id=None)

Get the child entities of the entity with given id.

Parameters:

  • include_params (bool) – True to include the parameters of the child entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

get_entity_siblings(entity_id, *, include_params=True, entity_type_names=None, privileged=False, workspace_id=None)

Get the sibling entities of the entity with given id.

Parameters:

  • include_params (bool) – True to include the parameters of the sibling entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

get_entity_revisions(entity_id, *, privileged=False, workspace_id=None)

Get all revisions of the entity with given id.

Parameters:

  • entity_id (int) – id of the entity to get the revisions from.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityRevisionList

get_entity_file(entity_id, *, privileged=False, workspace_id=None)

Get the file of the entity with given id.

Parameters:

  • entity_id (int) – id of the entity to get the file from.

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

File

Returns:

File object (SourceType.URL)

Raises:

ValueError – if file does not have a file associated with it.

get_current_user()

Get the current user in the environment.

Return type:

User

create_child_entity(parent_entity_id, entity_type_name, name, *, params=None, privileged=False, workspace_id=None, **kwargs)

Create a child entity with given name and type from parent entity with given id.

Warning

It is currently not possible to create a file-type entity

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. API.get_entity_children) within the same job because of memoization.

Parameters:

  • parent_entity_id (int) – id of the parent entity to create the child from.

  • entity_type_name (str) – type of the entity to be created (type must be a child-type of the parent entity).

  • name (str) – name of the entity to be created.

  • params (Union[dict, Munch]) – params to be stored on the newly created entity.

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

delete_entity(entity_id, *, privileged=False, workspace_id=None)

Delete the entity with given id.

Parameters:

  • entity_id (int) – id of the entity to be deleted.

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

None

rename_entity(entity_id, name, *, privileged=False, workspace_id=None)

Rename the entity with given id (creates a revision).

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.name) within the same job because of memoization.

Parameters:

  • entity_id (int) – id of the entity to rename.

  • name (str) – name of the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

set_entity_params(entity_id, params, *, privileged=False, workspace_id=None)

Create a new revision of the entity with given id, storing given params.

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.last_saved_params) within the same job because of memoization.

Parameters:

  • entity_id (int) – id of the entity to create a revision for.

  • params (Union[dict, Munch]) – params to be stored on the newly created entity revision.

  • workspace_id (int) – (optional) Provide id if you want to access resource from outside the context of the app

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

App​

class viktor.api_v1.App(api, id_, name, **_kwargs)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • api (_API) – API instance

  • id – ID of the App

  • name (str) – Name of the App

AppVersion​

class viktor.api_v1.AppVersion(api, id_, tag, status, app_type, sdk_version, python_version, created_at, **_kwargs)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • api (_API) – API instance

  • id – ID of the AppVersion

  • tag (str) – Tag of the AppVersion

  • status (str) – Status of the AppVersion publish

  • app_type (str) – Type of App as defined in the App definition

  • sdk_version (str) – Version of the SDK

  • python_version (str) – Version of the python

  • created_at (str) – Timestamp of when AppVersion was created.

Entity​

class viktor.api_v1.Entity(api, workspace_id, origin_id, operations, resolved=None)

Warning

Do not instantiate this class directly, it is created by the API.

children(*, include_params=True, entity_type_names=None, privileged=False)

Get the child entities.

Parameters:

  • include_params (bool) – True to include the parameters of the child entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

compute(method_name, *, params, timeout=None)

New in v14.12.0

Run a callable entity controller method (view-method, button-method, step-method or preprocess-method) and return the result.

Parameters:

  • method_name (str) – Name of the controller method to call

  • params (Union[dict, Munch]) – Params to call the method with

  • timeout (int) – Maximum job duration after which it will time out

Return type:

dict

Returns:

Return value of the controller method

create_child(entity_type_name, name, *, params=None, privileged=False, **kwargs)

Create a child entity with given name and type.

Warning

It is currently not possible to create a file-type entity

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. API.get_entity_children) within the same job because of internal caching.

Parameters:

  • entity_type_name (str) – type of the entity to be created (type must be a child-type of the parent entity).

  • name (str) – name of the entity to be created.

  • params (Union[dict, Munch]) – params to be stored on the newly created entity.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

delete(*, privileged=False)

Delete the entity.

Parameters:

privileged (bool) –

bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

None

property entity_type: EntityType

EntityType of the entity.

get_file()

Get the file of the entity.

Return type:

File

Returns:

File object (SourceType.URL)

Raises:

ValueError – if file does not have a file associated with it.

property id: int

id of the entity.

property last_saved_params: munch.Munch

Get the params of the last saved entity revision.

property last_saved_summary: munch.Munch

Get the summary of the last saved entity revision.

property name: str

Name of the entity.

parent(*, privileged=False)

Get the parent of the entity.

Parameters:

privileged (bool) –

bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

rename(name, *, privileged=False)

Rename the entity (creates a revision).

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.name) within the same job because of memoization.

Parameters:

  • name (str) – name of the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

revisions()

Get all revisions of the entity.

Return type:

EntityRevisionList

set_params(params, *, privileged=False)

Create a new revision of the entity, storing given params.

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.last_saved_params) within the same job because of memoization.

Parameters:

  • params (Union[dict, Munch]) – params to be stored on the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

siblings(*, include_params=True, entity_type_names=None, privileged=False)

Get the sibling entities.

Parameters:

  • include_params (bool) – True to include the parameters of the sibling entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

EntityList​

class viktor.api_v1.EntityList(api, workspace_id, relation, origin, entity_type_names, include_params, *, privileged=False)

Warning

Do not instantiate this class directly, it is created by the API.

Object which resembles a list of Entity objects.

Most commonly used list operations are supported:

# indexing
children = entity.children()
children[0]  # first child entity
children[-1]  # last child entity

# length
number_of_children = len(children)

# for loop
for child in children:
    # perform operation on child

EntityRevision​

class viktor.api_v1.EntityRevision(api, id_, params, created_date)

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • params (Munch) – Stored params in the entity’s revision.

  • created_date (datetime) – Date(time) of creation of the entity’s revision.

EntityRevisionList​

class viktor.api_v1.EntityRevisionList(api, entity, *, privileged=False)

Warning

Do not instantiate this class directly, it is created by the API.

Object which resembles a list of EntityRevision objects.

Most commonly used list operations are supported:

# indexing
revisions = entity.revisions()
revisions[0]  # first revision
revisions[-1]  # last revision

# length
number_of_revisions = len(revisions)

# for loop
for revision in revisions:
    # perform operation on revision

EntityType​

class viktor.api_v1.EntityType(api, id_, class_name, **_kwargs)

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • id – Unique ID of the entity type.

  • name – Entity type name (not label).

EntityTypeList​

class viktor.api_v1.EntityTypeList(api, workspace_id)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Object which resembles a list of EntityType objects.

Most commonly used list operations are supported:

# indexing
entity_types = api.get_entity_types()
entity_types[0]  # first entity_type
entity_types[-1]  # last entity_type

# length
number_of_entity_types = len(entity_types)

# for loop
for entity_type in entity_types:
    # perform operation on entity_type

FileResource​

class viktor.api_v1.FileResource(workspace_id, source_id, api=None)

File resource stored in the file manager.

Warning

Do not instantiate this class directly, it will be returned in the parameter set when using a FileField or MultiFileField.

property file: File

Returns the File object (URL-file) attached to the resource.

property filename: str

Returns the filename of the resource (API call required!).

Job​

class viktor.api_v1.Job(api, workspace_id, id_)

New in v14.12.0

Warning

Do not instantiate this class directly, it is created by the API.

get_result(*, timeout=15)

Obtain the job result

Return type:

dict

Returns:

Job result

Raises:

TimeoutError – If timeout is exceeded

Label​

class viktor.api_v1.Label(api, id_, name, description, color, **_kwargs)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • api (_API) – API instance

  • id – ID of the Label

  • name (str) – Name of the Label

  • description (str) – Description of the Label

  • color (str) – Color of the Label

User​

class viktor.api_v1.User(api, *, id_, first_name, last_name, email, job_title, **_kwargs)

User information.

Warning

Do not instantiate this class directly, it is created by the API.

Parameters:

  • id – user’s id

  • first_name (str) – user’s first name

  • last_name (str) – user’s last name

  • email (str) – user’s email address

  • job_title (str) – user’s job title

property full_name: str

User’s full name (first name + last name).

Workspace​

class viktor.api_v1.Workspace(api, id_, name, description, visibility, created_at, updated_at, is_archived, app, app_version, labels, **kwargs)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Can be used to fetch additional data within the given workspace.

# Get workspace object
workspace: Workspace = api.get_workspace(workspace_id)

# Iterate over underlying data
for entity in workspace.get_root_entities():
    ...
for entity_type in workspace.get_entity_types():
    ...
Parameters:

  • id – Unique ID of the workspace.

  • name (str) – Name of the workspace.

  • description (str) – Descriptive text of the workspace content.

  • visibility (str) – Visibility of the workspace. (Can be INTERNAL, PRIVATE, PUBLIC, or DEVELOPMENT)

  • created_at (str) – Timestamp of when workspace was created.

  • updated_at (str) – Timestamp of when workspace was last updated.

  • is_archived (bool) – Whether the workspace is archived.

  • app (Optional[dict]) – App assigned to the workspace. (Can be None for Development workspace)

  • app_version (Optional[dict]) – Published AppVersion assigned to the workspace. (Can be None for Development workspace)

  • labels (List[dict]) – Labels assigned to the workspace.

entity_compute(*, entity_id, method_name, params, timeout=None)

New in v14.12.0

Run a callable entity controller method (view-method, button-method, step-method or preprocess-method) and return the result.

Parameters:

  • entity_id (int) – ID of the entity to call the method from

  • method_name (str) – Name of the controller method to call

  • params (Union[dict, Munch]) – Params to call the method with

  • timeout (int) – Maximum job duration after which it will time out

Return type:

dict

Returns:

Return value of the controller method

get_entity(id_, privileged=False)

Get the entity with given id.

Parameters:

  • id – entity_id

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

Entity

get_entity_type(id_)

Get the entity type with given id in the workspace.

Return type:

EntityType

get_entity_types()

Get the entity types in the workspace.

Return type:

EntityTypeList

get_root_entities(*, include_params=True, entity_type_names=None, privileged=False)

Get the root entities.

Parameters:

  • include_params (bool) – True to include the parameters of the root entities.

  • entity_type_names (List[str]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in viktor.config.toml. This is to provide an additional layer of security / awareness. Restrictions can only be bypassed when using the API module within a VIKTOR app and within the context of the current workspace.

Return type:

EntityList

WorkspaceList​

class viktor.api_v1.WorkspaceList(api, app_name=None, include_archived=False)

New in v14.9.0

Warning

Do not instantiate this class directly, it is created by the API.

Object which resembles a list of Workspace objects.

Most commonly used list operations are supported:

# indexing
workspaces = api.get_workspaces()
workspaces[0]  # first workspace
workspaces[-1]  # last workspace

# length
number_of_workspaces = len(workspaces)

# for loop
for workspace in workspaces:
    # perform operation on workspace