bytekit-sdk

Official Python SDK for the ByteKit API.

The PyPI distribution is bytekit-sdk; the import name is bytekit.

Generated from the OpenAPI spec using openapi-python-client, filtered to the stable v0.1 operations.

Installation

pip install bytekit-sdk

The installed version is available as bytekit.__version__.

Quick start

from bytekit import AuthenticatedClient
from bytekit.api.scrape import create_scrape
from bytekit.models.scrape_request import ScrapeRequest
from bytekit.models.scrape_request_formats_item import ScrapeRequestFormatsItem
from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope

# base_url defaults to https://api.bytekit.com, so only the token is required.
client = AuthenticatedClient(token="sk_live_your_api_key_here")

result = create_scrape.sync(
    client=client,
    body=ScrapeRequest(
        url="https://example.com",
        # Ask for markdown explicitly. `formats` is a list of enum members, not plain
        # strings. Omit it and the server returns raw HTML instead, leaving
        # `formats.markdown` unset.
        formats=[ScrapeRequestFormatsItem.MARKDOWN],
    ),
)

if isinstance(result, ScrapeSuccessEnvelope):
    print(result.formats.markdown)

See Error handling for what result can be when the request fails.

Error handling

The SDK has a two-tier error contract. Both tiers are safe: an operation never raises a bare json.JSONDecodeError, even when a server returns an HTML error page.

from bytekit import AuthenticatedClient
from bytekit.api.scrape import create_scrape
from bytekit.errors import UnexpectedStatus
from bytekit.models.error import Error
from bytekit.models.scrape_request import ScrapeRequest
from bytekit.models.scrape_success_envelope import ScrapeSuccessEnvelope

client = AuthenticatedClient(token="sk_live_your_api_key_here")

try:
    result = create_scrape.sync(client=client, body=ScrapeRequest(url="https://example.com"))
except UnexpectedStatus as err:
    # Undocumented status, or a non-JSON body on a documented one. Never a JSONDecodeError.
    print(f"request failed with status {err.status_code}: {err.code} {err.message}")
else:
    if isinstance(result, Error):
        # Documented 4xx/5xx with a JSON body: RETURNED as a typed model, not raised.
        print(f"api error {result.error.code}: {result.error.message}")
    elif isinstance(result, ScrapeSuccessEnvelope):
        print(result.formats.markdown)
    else:
        # 202 ScrapeQueuedEnvelope — poll get_scrape with this id until it completes.
        print(f"queued as {result.id}")

Defaults

The client ships with production-ready defaults so AuthenticatedClient(token=...) works out of the box:

Explicit constructor arguments always win over these defaults (explicit arg > default).

Async usage

import asyncio
from bytekit import AuthenticatedClient
from bytekit.api.screenshots import create_screenshot
from bytekit.models.screenshot_request import ScreenshotRequest

async def main():
    client = AuthenticatedClient(token="sk_live_your_api_key_here")
    body = ScreenshotRequest(url="https://example.com")
    response = await create_screenshot.asyncio(client=client, body=body)
    print(response)

asyncio.run(main())

Clients and event loops

An httpx.AsyncClient — and therefore its connection pool — belongs to the event loop that created it. The recommended shape is a context manager, which scopes the client to exactly one loop:

async def main():
    async with AuthenticatedClient(token="sk_live_your_api_key_here") as client:
        ...

Two rules cover everything else:

• A client the SDK builds for you is rebuilt automatically. If you reuse one client across several asyncio.run(...) calls, the SDK notices the running loop has changed and transparently replaces its internal AsyncClient. Your base_url, headers, timeout, httpx_args and authentication are all re-applied, so this is invisible apart from a new connection. Calling get_async_httpx_client() outside any running loop returns the cached client unchanged.
• A client you pass to set_async_httpx_client(...) is yours. The SDK never rebuilds or closes it, so a client you supply must be created and used on the same loop — that is the one case where crossing loops is still your responsibility.

Available operations

License

MIT — see LICENSE.