Skip to main content

Vilocify SDK and CLI tool

The Python SDK for Vilocify, built using Vilocify's APIv2 JSON:API. This project also includes a CLI tool to manage Vilocify Monitoring Lists e.g. to update or create lists from CycloneDX SBOM files.

Prerequisites

The Vilocify SDK needs Python 3.12 or newer.

CLI usage

  1. Get pipx
  2. Install the CLI with pipx install vilocify-sdk
  3. Run vilocify --help for documentation of the CLI tool

Example

Following example imports a monitoring list from a CycloneDX SBOM. Note that the monitoring list is identified by its name. If a monitoring list with the same name already exists, it gets overwritten with the contents from the SBOM file.

vilocify monitoringlist import --name "My Project v1.2.3" --from-cyclonedx my_project_v1.2.3.sbom.json

Example: Tenant with group feature enabled

If the example above gave you the error Organization group must exist, you must specify the --group parameter on import. Valid values for --group can be listed with vilocify groups.

vilocify monitoringlist import --name "My Project v1.2.3" --group "ABC" --from-cyclonedx my_project_v1.2.3.sbom.json

SDK usage

The SDK is built on Vilocify's API. We recommend you also take a quick look at the raw API docs at https://portal.vilocify.com/documentation. In particular, study the "API resources" section and filter[...][...] parameters of main resources. Those will come in handy for understanding the models of the SDK and arguments that can be used in .where() methods.

Installation

Get vilocify-sdk from PyPI. If you use Poetry get it with poetry add vilocify-sdk.

Authentication

You can generate an API Token at https://portal.vilocify.com/api-tokens.

By default, authentication for the SDK is configured through the VILOCIFY_API_TOKEN environment variable. Alternatively, the token can be set programmatically:

from vilocify import api_config

api_config.token = "<your token here>"

Examples

Inviting a new member into your org

Note that this code needs a token with "admin" role.

from vilocify.models import Membership

m = Membership(username="John Doe", email="john.doe@example.com", role="user", expires_at="2025-10-30T00:00:00Z")
m.create()

print(m.invitation_state)
print(m.created_at)

Creating a monitoring list

from vilocify.models import MonitoringList, Subscription, Component, Membership

# Creating a new monitoring list automatically adds the authenticated user as 'owner'
ml = MonitoringList(name="Example list", comment="created by the Vilocify SDK")
ml.components = [Component(id="40866"), Component(id="148860")]
ml.create()

# Add a second subscriber to the list.
sub = Subscription(role="reader")
sub.monitoring_list = ml
sub.membership = Membership.where("email", "eq", "john.doe@example.com").first()
sub.create()

for subscription in ml.subscriptions:
    print(subscription.membership.email, "-", subscription.role)

Listing notifications for a monitoring list

from vilocify.models import MonitoringList, Notification

ml = MonitoringList.where("name", "eq", "Example list").first()

# Find Vilocify notifications for the monitoring list since 2023
notifications = Notification.where("monitoringLists.id", "any", ml.id).where(
    "createdAt", "after", "2023-01-01T00:00:00Z"
)
for n in notifications:
    print(n.title)

Filtering

To filter models by supported attributes, use the .where() method, which takes three arguments. The three arguments map 1-to-1 to filter parameters described in the API Docs.

Take for example following request with a filter parameter from the docs:

GET /api/v2/notifications?filter[monitoringLists.id][any]=8c63252a-893e-4563-876b-a45ac9bdfff2

The corresponding Python code is

Notification.where("monitoringLists.id", "any", "8c63252a-893e-4563-876b-a45ac9bdfff2")

The third parameter of .where() can either be a string or a list of strings. Note that the SDK does not perform further validations which operators accept lists and which don't; lists simply get concatenated to comma-separated strings. Check the API docs which filters support multiple values.

Sorting

Sorting is handled by .asc() and .desc(). Check the documentation of the sort parameter in top-level GET /api/v2/{resources} in the API Docs for available sorters. The Vilocify API can only sort by a single attribute and does not support sorting by multiple attributes. The SDK will raise an exception when attempting to sort an already sorted request.

Relationships

The models.py module defines the SDK models and their relationships, which closely reflects the "API Resources" drawing of the API Docs. Relationships cannot be set through the model constructor, but instead must be set using assignment. For example:

sub = Subscription(role="user")  # role is an attribute
sub.membership = Membership(id="<a_membership_id_here>")  # `.membership` is a to-one relation
sub.monitoring_list = MonitoringList(id="<a_ml_id_here>")  # `.monitoring_list` is a to-one relation
sub.create()  # Performs the API request to create the subscription


ml = MonitoringList(name="Example list")  # name is an attribute
ml.components = [  # components is a to-many relationship
    Component(id="40866"),
    Component(id="148860"),
]
ml.create()  # Creates a monitoring list with the two given components

Updating to-many relationships

The SDK provides two mechanisms to update to-many relationships. One replaces all existing relationships and is not immediate, but needs a call to .update(). The other extends the existing relationship and is immediate. For example

ml = MonitoringList.first()
ml.components = [  # Replaces all components on the monitoring list, no request is sent, yet.
    Component(id="1"),
    Component(id="2"),
]
ml.update()  # Commit the change to the Vilocify API


ml = MonitoringList.first()
ml.components.extend(
    Component(id="3"), Component(id="5")
)  # Adds component with IDs 1 and 2, and immediately sends the change to the API backend

Proxy setup

The SDK uses a requests.Session() to handle its HTTP requests, which picks up the proxy settings from the https_proxy environment variable as documented here. To override that behavior do the following:

from vilocify import api_config

api_config.client.trust_env = False
api_config.client.proxies = {"https": "https://your.proxy:8080"}

Contributing

See Contributing.md.

License

MIT License

Copyright (c) 2026 Siemens AG

Metadata

Release files for vilocify-sdk 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vilocify-sdk 0.10.0
File Size Uploaded Provenance Actions
vilocify_sdk-0.10.0.tar.gz 18.5 kB With provenance Details for vilocify_sdk-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vilocify-sdk 0.10.0
File Interpreter ABI Platform Actions
vilocify_sdk-0.10.0-py3-none-any.whl Python 3 none any Details for vilocify_sdk-0.10.0-py3-none-any.whl

Total release size: 37.2 kB

Release files / vilocify_sdk-0.10.0.tar.gz

Download URL vilocify_sdk-0.10.0.tar.gz
Size 18.5 kB
Tags Source
SHA-256 checksum
How to use checksums
87cb028bdb523070e47bb541a311fcb7dc1b18bb4ba6422d3cf27f6afa65ed8a
BLAKE2b-256 checksum
How to use checksums
f5a2023ca4e3157113cb5230d6301db14c7cdb58be4db20c64aa2cf6f2ae3205
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Release files / vilocify_sdk-0.10.0-py3-none-any.whl

Download URL vilocify_sdk-0.10.0-py3-none-any.whl
Size 18.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3db34e751775f459d49f32be3a984c867735aa1afa6bbf4d87d945d70e5c1508
BLAKE2b-256 checksum
How to use checksums
a4dca2b6ef1fb72a0fbcefbb709b0806ecc1d7b84c0a3d77b9205e50195dbb97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

Security for vilocify-sdk 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vilocify_sdk-0.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page