Orvelt

Orvelt Python SDK

Install and configure the Orvelt Python SDK, read typed results, handle errors, and upgrade the client.

The Orvelt Python SDK (orvelt-business, Python 3.10+) exposes 12 selected operations from the Business REST API. It is generated from the same contract as the HTTP API. The Developer quickstart creates a key and sends a first request; this page covers the Python client in detail.

Install

The Python package is not yet on PyPI. Install it from a checkout of orveltinc/python-sdk:

python -m pip install .

Functions

Operations use the same single-word resource and action names as the API. For example, link.create calls POST /project/{projectId}/link.

Resource groups

GroupFunctions
questionslist, create, update, delete
opinionslist
answerslist
linklist, create, resend
qrdisplay
subscriberscount, invite

The HTTP API reference also includes endpoints the SDK does not export.

Pass parameters as one flat object

Pass keyword arguments in snake_case, including project_id on every call. Requests still use the API's camelCase field names.

import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(project_id="PROJECT_ID", page=1, limit=20)

Configure the client

Client options

Create an Orvelt client and close its connections with a context manager:

import os
from orvelt_business import Orvelt

with Orvelt(
    business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"],
    server_url=os.environ.get("ORVELT_API_BASE_URL", "https://api.orvelt.com/v1"),
    timeout_ms=10_000,
) as client:
    page = client.opinions.list(
        project_id="PROJECT_ID",
        http_headers={"x-request-id": "REQUEST_ID"},
    )
  • server_url overrides the default https://api.orvelt.com/v1; include /v1 for staging or a local proxy.
  • timeout_ms sets a request timeout.
  • client and async_client accept custom HTTPX-compatible transports.
  • Per-operation http_headers adds request headers.

Every method has an async equivalent with an _async suffix. Use async with and await it inside your async service:

import asyncio
import os
from orvelt_business import Orvelt

async def main():
    async with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
        page = await client.opinions.list_async(project_id="PROJECT_ID")
        print({"count": len(page.result.opinions)})

asyncio.run(main())

Use separate clients

Create a separate Orvelt instance for each environment or organization. Each instance holds its own credentials; there is no shared global client.

import os
from orvelt_business import Orvelt

with Orvelt(
    business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"],
    server_url=os.environ.get("ORVELT_API_BASE_URL", "https://api.orvelt.com/v1"),
) as client:
    page = client.opinions.list(project_id="PROJECT_ID")

Bind a project ID

Python has no useProject helper. Store the ID once and pass project_id explicitly:

import os
from orvelt_business import Orvelt

project_id = os.environ["ORVELT_PROJECT_ID"]
with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(
        project_id=project_id,
        external_user_id="customer-42",
        visibility="public",
    )

Read results and errors

The Python SDK returns typed Pydantic models and raises HTTP errors rather than returning a { data, error } envelope. Non-paginated operations return their typed response directly:

import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    result = client.link.create(
        project_id="PROJECT_ID",
        customer_email="[email protected]",
        customer_first_name="Alex",
        customer_reference="ORDER-42",
    )
    emailed_at = result.emailed_at

opinions.list, answers.list, and link.list return a page wrapper with the typed response in .result. Call .next() (or await page.next() for async calls) to fetch another page; it returns None after the last page. Filters, credentials, and page size carry over. See Pagination.

Errors lists every status and code. Log only the status, error code, and counts you need; keep customer records, opinion text, delivery links, credentials, and raw error objects out of logs.

Throw on errors

HTTP failures always raise subclasses of orvelt_business.errors.OrveltError; there is no throwOnError setting. Inspect status_code and headers to decide how to recover. Invalid response shapes raise ResponseValidationError; transport failures raise HTTPX errors.

import logging
import os
from orvelt_business import Orvelt, errors

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    try:
        page = client.opinions.list(project_id="PROJECT_ID")
        print({"count": len(page.result.opinions)})
    except errors.OrveltError as error:
        logging.error("Business API request failed: HTTP %s", error.status_code)
        raise

Retry transient failures

GET requests retry connection failures and HTTP 429, 500, 502, 503, and 504 with bounded backoff. Pass retries=None to disable read retries for an operation:

import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(project_id="PROJECT_ID", retries=None)

Mutations do not retry by default, including link issuance, invitations, and rotating QR display. Do not replay these automatically: the first attempt may have succeeded.

Upgrade the SDK

TypeScript and Python ship together as one SDK release, with shared notes in the SDK changelog. The notes identify each package's changes and versions; breaking changes say what to update. Business app and HTTP API changes are released separately under Business releases.

Versions and ranges

Versions follow semantic versioning: patch releases are fixes only, minor releases add functions or options without breaking existing calls, and major releases contain breaking changes.

For upgrades, check out the Python version named in the shared SDK release notes and reinstall it:

python -m pip install .

A prepared SDK release is not published until both packages have shipped.