Installation and authentication

Install¶

The SDK is published on PyPI as vilvik and supports Python 3.9 and newer. The source is open on GitHub.

pip install vilvik

If you keep your project on Poetry or uv, add vilvik to your dependencies the usual way.

Get an API key¶

You need an API key to use the SDK. Keys live on the API page of your account: open it from the main menu or the Creating and managing API keys doc page. A key looks like vlk_live_…. Keep it secret.

Choose the scopes you need when you create the key. The SDK uses the same scopes the REST API uses, so a key valid for submissions:write and results:read works for both. See Scopes and permissions.

Tell the SDK about your key¶

The client reads the key from two places, in this order:

1. The api_key argument you pass to vilvik.Client(...).
2. The VILVIK_API_KEY environment variable.

Pick the option that fits your project. For a script, an environment variable is usually safest:

export VILVIK_API_KEY=vlk_live_...

import vilvik

client = vilvik.Client()  # reads VILVIK_API_KEY

For tools that need to switch between keys, pass it explicitly:

client = vilvik.Client(api_key="vlk_live_...")

If neither is set, the constructor raises ValueError.

Client configuration¶

The Client constructor accepts these keyword arguments:

client = vilvik.Client(
    api_key="vlk_live_...",
    base_url="https://staging.vilvik.example/api/v1",
    timeout=120.0,
    max_retries=3,
)

The configured base URL is exposed as client.base_url for inspection.

Liveness probe¶

client.health() returns the raw response from the API's /health endpoint. Use it to confirm credentials and connectivity from a fresh environment.

print(client.health())

REST equivalent: GET /api/v1/health.

Related pages¶

• Creating and managing API keys
• Authentication
• Scopes and permissions
• Errors and exceptions