Python SDK

The official Python client for Syttra. Typed Pydantic v2 response models, structured exceptions per HTTP status, automatic retries with exponential backoff, sitemap pre-flight, and a wait_for_job helper. Python 3.10+.

Install

$pip install syttra

Repo: github.com/syttra/syttra-python · pypi.org/project/syttra

Quickstart

Create an API key at /dashboard/keys. The SDK reads SYTTRA_API_KEY from the environment so you don't need to pass it explicitly.

python

from syttra import Syttra

client = Syttra(api_key="sk_live_...")

# 1. Submit a job
job = client.create_job(url="https://en.wikipedia.org/wiki/White_House")

# 2. Wait for it to finish (polls every 2s, 10-min timeout)
finished = client.wait_for_job(job.job_id)

# 3. Download the result
result = client.get_job_result(finished.job_id)
print(result.body)        # markdown by default
print(result.filename)    # "job-<id>.md"

Crawl modes

Three shapes — single page, full same-domain crawl, or an explicit URL list (typically picked from a sitemap preview).

python

from syttra import Syttra, CrawlMode

client = Syttra()

# Discover URLs first
preview = client.preview_sitemap("https://example.com")
chosen = [u for u in preview.urls if "/blog/" in u]

# Crawl just those
job = client.create_job(
    url="https://example.com",
    mode=CrawlMode.SELECT,
    urls=chosen,
)

Errors

Every non-2xx response raises a typed exception. Catch by class, not by status code.

python

from syttra import Syttra, QuotaExceeded, Unauthorized, ApiError

try:
    job = client.create_job(url="https://example.com")
except QuotaExceeded as exc:
    print("Out of pages this month: ", exc.details)
except Unauthorized:
    print("API key revoked or wrong env")
except ApiError as exc:
    # Generic fallback. Carries .status, .code, .message, .details, .request_id
    print(f"{exc.status} {exc.code}: {exc.message}")

request_id is what we'll ask for if you open a support ticket — copy it from exc.request_id.

Retries

The SDK retries 429 and gateway errors (502, 503, 504) up to three times with exponential backoff. Retry-After headers are honoured. Plain 500 errors are not retried by default — opt in via RetryPolicy(retry_on_5xx=True).

python

from syttra import RetryPolicy, Syttra

client = Syttra(
    retry=RetryPolicy(
        max_attempts=5,
        retry_on_5xx=True,
    ),
)

What's coming

v0.2 — async client (AsyncSyttra), same surface, await throughout.
v0.3 — OpenAPI-generated models so the SDK never lags the API.

Want a different language?

TypeScript / Go / .NET clients are next on the roadmap. Until they ship, the public REST API works from any language.

Read the REST docs