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 or a bare KeyError, even when a server returns an HTML error page or a payload whose shape has drifted from the spec.

A failed scrape is a result, not a transport error, so the API reports it on a 200 rather than a 5xx — but a returned failure is exactly the shape a first call misreads as success (result.formats on a ScrapeErrorEnvelope is an AttributeError). create_scrape therefore raises it. The carve-out is that one call: the identical envelope from get_scrape is the correct answer to "how did that job end?" and is still returned.

The table describes the generated operations (create_scrape.sync, get_usage.sync, …), whose return types are Optional[...] accordingly. The hand-written AuthenticatedClient.search(...) convenience method is deliberately outside it: it returns a non-Optional CreateSearchResponse200 and raises errors.UnexpectedStatus on anything else — including documented error statuses, and including a malformed 200 — in both raise modes. raise_on_unexpected_status does not apply to it.

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_request_formats_item import ScrapeRequestFormatsItem
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",
            # Ask for markdown explicitly — omit `formats` and the server returns raw HTML,
            # leaving `formats.markdown` unset.
            formats=[ScrapeRequestFormatsItem.MARKDOWN],
        ),
    )
except UnexpectedStatus as err:
    # Undocumented status, a non-JSON body on a documented one, or a 200 whose envelope
    # says the scrape itself failed. 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}")

Transport errors

Both tiers above describe what happens once the server has answered. When it never does, the underlying httpx exception propagates unchanged — the SDK catches neither, on every generated operation and on search(...) alike:

raise_on_unexpected_status does not apply to either — it governs how a response is handled, and there is no response in these cases. Catch them alongside errors.UnexpectedStatus:

except (UnexpectedStatus, httpx.TimeoutException, httpx.ConnectError) as err: ...

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).

Every constructor argument is keyword-only

AuthenticatedClient accepts no positional arguments. token, base_url, prefix, auth_header_name and the rest are all passed by name:

client = AuthenticatedClient(base_url="https://api.bytekit.com", token="sk_live_your_api_key_here")

Migrating from a pre-0.3.0 positional call. base_url used to be the first positional argument, so AuthenticatedClient("https://…", "sk_live_…") was a documented call. Once base_url became a defaulted keyword argument, that same call silently bound the URL to token and the API key to prefix — producing an Authorization: sk_live_… https://… header sent to the default host, i.e. a wrong credential against production with nothing raised. Since 0.3.5 it raises TypeError instead. Add the keywords; nothing else changes.

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

Two things worth knowing before your first call

get_fetch takes url_query=, not url=. The URL to fetch is passed as url_query; it travels as the url query parameter on the wire. The rename comes from the generator, which avoids reusing url for an operation argument. get_fetch.sync(client=client, url="…") is a TypeError:

from bytekit import AuthenticatedClient
from bytekit.api.fetch import get_fetch

client = AuthenticatedClient(token="sk_live_your_api_key_here")
result = get_fetch.sync(client=client, url_query="https://example.com")

AuthenticatedClient.search(...) is synchronous. Calling it from inside a coroutine blocks the event loop for the duration of the request — nothing raises, so it is easy to miss. In async code use the generated operation instead, which is a real coroutine:

from bytekit.api.search import create_search
from bytekit.models.create_search_body import CreateSearchBody

response = await create_search.asyncio(client=client, body=CreateSearchBody(query="climate tech"))

The convenience method's extra behavior — raising errors.UnexpectedStatus on every non-200 rather than returning a typed Error — is its own, and create_search.asyncio follows the two-tier contract described under Error handling like every other generated operation.

License

MIT — see LICENSE.