Python SDK

Drive your hosting from Python

zinn-sdk is a typed Python client for the Zinn Digital® API, generated from the same OpenAPI specification the API is built from. Every operation has synchronous and asyncio variants, and every request and response is a typed model.

All developer docs →

Install

The package is on PyPI as zinn-sdk and is imported as zinn_sdk. It needs Python 3.11 or later.

pip install zinn-sdk

Quick start

List the public hosting regions without a key, then list your own sites with one.

import os

from zinn_sdk import AuthenticatedClient, Client
from zinn_sdk.api.catalog import list_public_hosting_regions
from zinn_sdk.api.hosting import list_sites

# Public catalogue endpoints need no key.
public = Client(base_url="https://api.zinndigital.com")
regions = list_public_hosting_regions.sync(client=public)
print([region.slug for region in regions.data])

# Everything else uses a per-organisation API key.
api = AuthenticatedClient(base_url="https://api.zinndigital.com", token=os.environ["ZINN_API_KEY"])
page = list_sites.sync(client=api, limit=5)
for site in page.data:
    print(site.name, site.status)

Authentication

Public catalogue endpoints, such as regions and plans, need no credential. Everything else uses a per-organisation API key passed to AuthenticatedClient, which sends it as a bearer token. A key carries only the permissions you grant it when you create it, and you can revoke it at any time. Keep it in an environment variable or your secret store, never in source code.

Create an API key in your dashboard

What you get

Typed models

Requests and responses are attrs models with type hints, so your editor and your type checker understand every field.

Sync and asyncio

Each operation has sync, sync_detailed, asyncio and asyncio_detailed functions, named after the operation in snake case and grouped by API area under zinn_sdk.api.

Generated from the specification

A new version is published automatically whenever the OpenAPI specification changes. The few operations the generator cannot express yet are listed and checked on every release, and stay available through the REST API.

Async calls

The same call with asyncio, returning the HTTP status as well as the parsed response.

import asyncio

from zinn_sdk.api.hosting import list_sites

# Every operation has sync, sync_detailed, asyncio and asyncio_detailed variants.
async def main() -> None:
    response = await list_sites.asyncio_detailed(client=api, limit=5)
    print(response.status_code, len(response.parsed.data))

asyncio.run(main())

Questions

Do you have a Python SDK?

Yes. Install zinn-sdk from PyPI with pip install zinn-sdk and import zinn_sdk. It is a typed client generated from our OpenAPI specification, with synchronous and asyncio calls.

Where is a given endpoint in the Python SDK?

Operations are grouped by API area under zinn_sdk.api and named after their operation id in snake case. For example, listing sites is zinn_sdk.api.hosting.list_sites.

Which Python versions are supported?

Python 3.11 and later.

Explore every endpoint

Every operation the SDK can call is described in the API reference, with its parameters, responses and permissions.

API reference