Python SDK

from constaia import Constaia

client = Constaia()  # reads CONSTAIA_API_KEY

analysis = client.analyze(
    "dni_valid.jpg",
    expect="es_dni",
    checks={"not_expired": True, "holder": {"full_name": "María García López"}},
    language="en",
)

verdict = analysis["verdict"]
if verdict and verdict["status"] == "valid":
    print(analysis["fields"]["document_number"]["value"])  # 12345678Z
elif verdict and verdict["status"] == "review":
    print("Manual review:", analysis["warnings"])
else:
    for reason in verdict["reasons"] if verdict else []:
        print(reason["code"], reason["message"])

import asyncio

from constaia import AsyncConstaia


async def main() -> None:
    async with AsyncConstaia() as client:
        analysis = await client.analyze(file_url="https://example.com/id.jpg", expect="es_dni")
        print(analysis["verdict"])
        async for item in client.analyses.list(status="completed"):
            print(item["id"])


asyncio.run(main())

import httpx
from constaia import Constaia

client = Constaia(
    api_key="ck_live_...",  # default: CONSTAIA_API_KEY
    base_url="https://api.constaia.com",  # default; or CONSTAIA_BASE_URL
    timeout=60.0,  # seconds per attempt
    max_retries=2,  # 0 disables retries
    max_concurrency=4,  # requests in flight at once; the rest wait in the client
    default_headers={"X-Team": "ops"},
    http_client=httpx.Client(proxy="http://proxy:8080"),  # optional
)

analysis = client.analyze(
    "id.jpg",
    expect=["es_dni", "es_nie", "passport"],  # without expect there is no verdict
    checks={
        "not_expired": True,
        "min_age_years": 18,
        "holder": {"full_name": "María García López", "document_number": "12345678Z"},
        "require_fields": ["birth_date"],
    },
    extract=True,  # or your own JSON Schema (dict)
    storage="none",  # "none" | "temporary" | "persistent"
    ttl_hours=24,  # with "temporary"
    keep_results=True,
    async_=False,  # True → 202 and webhook
    export=["xlsx", "json"],
    metadata={"registration_id": "123"},
    language="en",
    idempotency_key="registration-123-id",  # optional: your own
    timeout=90,
)

client.analyze(file, **options)
client.classify(file, expect="invoice")  # 0.2 credits

client.analyses.get("an_01J…")
page = client.analyses.list(limit=50, status="completed", type="es_dni", metadata={"event": "42"})
page.data, page.has_more  # first page
for a in client.analyses.list(type="es_dni"):  # iterating walks every page
    print(a["id"])
recent = client.analyses.list().to_list(200)
client.analyses.delete("an_01J…")
client.analyses.export("an_01J…", "xlsx", save_to="analysis.xlsx")  # returns the bytes

client.batches.create(items=[{"file_url": "https://example.com/1.pdf"}], options={"expect": "invoice"})
client.batches.create(files=["a.jpg", "b.pdf"], options={"expect": "payment_receipt"})
client.batches.get("bat_01J…")

client.document_types.list(language="en")
client.document_types.get("medical_certificate_sport")

endpoint = client.webhook_endpoints.create(
    url="https://example.com/webhooks/constaia",
    events=["analysis.completed", "analysis.review_required"],
)
endpoint["secret"]  # whsec_… — only shown now
client.webhook_endpoints.list()
client.webhook_endpoints.get("we_01J…")
client.webhook_endpoints.delete("we_01J…")

client.balance()
client.usage(from_="2026-09-01", to="2026-09-30")

from constaia.types import Analysis


def is_ok(a: Analysis) -> bool:
    return a["verdict"] is not None and a["verdict"]["status"] == "valid"

from constaia import (
    ConstaiaError,
    InsufficientCreditsError,
    InvalidRequestError,
    RateLimitError,
)

try:
    client.analyze("id.jpg", expect="es_dni")
except InvalidRequestError as e:
    print(e.code, e.param)  # e.g. unsupported_file_type, file
except InsufficientCreditsError:
    notify_billing()
except RateLimitError as e:
    print(f"retry in {e.retry_after} s")
except ConstaiaError as e:
    print(e.status, e.type, e.request_id)

client.balance()
client.last_rate_limit  # RateLimit(limit=10, remaining=9, reset=1, policy='10;w=1', retry_after=None)
client.last_request_id  # "req_…": quote it when contacting support

import constaia

event = constaia.webhooks.verify(raw_body, headers, "whsec_...")  # raises WebhookVerificationError
if event["type"] == "analysis.completed":
    save(event["data"])