Bookivox Python SDK

Official Python client and CLI for the Bookivox API: typed access to agents, node types, tools, knowledge-base documents, recordings, credentials and test calls.

• Typed: generated TypedDict models and typed method signatures (py.typed).
• Safe by default: timeouts, retries on idempotent verbs only, typed errors, no secret logging.
• One install: pip install bookivox gives you both the SDK and the bookivox CLI.
• Single runtime dependency: httpx.

Requirements

• Python 3.11 or newer.
• A Bookivox API key (bookeys_sk-...), created in API keys.

Install

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
pip install bookivox

uv add bookivox      # or: poetry add bookivox

Verify the installation:

python -c "import bookivox_sdk; print(bookivox_sdk.__version__)"
bookivox --version

Authenticate

The API key is read from the api_key argument, then from BOOKIVOX_API_KEY:

export BOOKIVOX_API_KEY="bookeys_sk-..."

import os
from bookivox_sdk import Bookivox

client = Bookivox(
    api_key=os.environ["BOOKIVOX_API_KEY"],  # or omit to use the env var
    timeout=30.0,
    max_retries=2,                           # idempotent requests only
)

The API origin is https://api.bookivox.com and is not configurable.

Quick start

import os
from bookivox_sdk import Bookivox

with Bookivox(api_key=os.environ["BOOKIVOX_API_KEY"]) as client:
    for workflow in client.list_workflows():
        print(workflow["id"], workflow.get("name"))

Bookivox is a context manager: with closes the underlying connection pool.

Methods

Errors

from bookivox_sdk import (
    Bookivox,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

try:
    with Bookivox() as client:
        client.get_workflow("wf_123")
except AuthenticationError:
    ...  # 401: invalid or revoked key
except NotFoundError:
    ...  # 404: unknown agent, or outside your organization
except ValidationError as exc:
    print(exc.status_code, exc.body)
except RateLimitError as exc:
    print("retry in", exc.retry_after, "s")

Every APIStatusError exposes status_code, request_id and body.

CLI

bookivox login --api-key "$BOOKIVOX_API_KEY"
bookivox config
bookivox workflows list --json

Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 rate limit, 6 connection.

Security

• Never commit .env files; load the key from your platform's secret manager.
• test_phone_call triggers a real, billable phone call.

Generated code

src/bookivox_sdk/models.py and src/bookivox_sdk/_generated.py are generated from the API OpenAPI schema and must never be edited by hand. Regenerate them with ./generate_sdk.sh from the repository root.

Full documentation: https://docs.bookivox.com/sdk/overview.