Crimson Crawler Python SDK

Typed, async threat intelligence for Python.

Documentation · PyPI · GitHub · Get an API key

Turn a CVE into a complete, typed attack briefing with one async call. The client also covers package, IOC, CWE, and ATT&CK enrichment, artifact and inventory workflows, grounded reports, and every v1 endpoint without hand-written request models.

Install

pip install crimson-crawler-client
# or
uv add crimson-crawler-client

Python 3.11+.

PyPI publication is pending. The install command above applies once the first release lands; until then, use the repository checkout for evaluation. The badge above will show the registry version once that release succeeds.

Authentication

Set your key in the environment:

export CRIMSON_CRAWLER_API_KEY=your-api-key

Or pass it directly (preferred for tests and multi-tenant code):

async with CrawlerClient(api_key="your-api-key") as client:
    ...

The constructor argument wins over the env var. Generate a key at crimsoncrawler.com/dashboard.

Custom or local endpoint

The hosted API at https://crimsoncrawler.com is the default. Point the official package at a local or self-hosted deployment with either form:

export CRIMSON_CRAWLER_BASE_URL=http://localhost:8000

client = CrawlerClient(base_url="http://localhost:8000")

The SDK sends its apikey header to the selected origin. Use a local or development key when overriding the endpoint; do not reuse a production key with an origin you do not control. Custom non-loopback endpoints must use HTTPS. Plain HTTP is accepted only for loopback development URLs such as the example above. TLS verification stays enabled by default; trust the deployment's CA when possible. verify_ssl=False or CRIMSON_CRAWLER_VERIFY_SSL=false is only for isolated local development with a self-signed certificate. The SDK emits a warning for either override.

Quick start

import asyncio
from crimson_crawler_client import CrawlerClient


async def main() -> None:
    async with CrawlerClient() as client:
        result = await client.enrich_cve_full("CVE-2024-3400")

        if result.cve:
            print(result.cve.cvss_score)

        for technique in result.techniques or []:
            print(technique.technique_id, technique.name)


asyncio.run(main())

Every list-valued field on an enrichment response can be None if that layer wasn't requested or had no data. The or [] guard is the standard pattern.

The client

Constructor

CrawlerClient(
    api_key: str | None = None,
    base_url: str | None = None,
    verify_ssl: bool | None = None,
    max_retries: int = 2,
)

Raises MissingCredentials if neither api_key nor the env var is set. Raises ValueError for a malformed or insecure non-loopback base_url, or if max_retries < 0.

Properties

• api — pass this to any endpoint function when calling endpoints directly (see Beyond the convenience surface).
• base_url — read-only; the resolved hosted, custom, or local endpoint.
• max_retries — read-only; the configured retry budget (see Retry & rate limits).

Async lifecycle

CrawlerClient is an async context manager. The recommended pattern:

async with CrawlerClient() as client:
    result = await client.enrich_cve_full("CVE-2024-3400")

Entering opens the HTTP client. Exiting closes it.

If you need finer control:

client = CrawlerClient()
try:
    result = await client.enrich_cve_full("CVE-2024-3400")
finally:
    await client.aclose()

A single CrawlerClient can issue many concurrent requests. TCP connections are reused across calls, so don't construct one per request.

Convenience methods

Every /v1 operation has a method — 33 of them, plus the search_techniques shortcut. The seven documented in full below cover the highest-traffic patterns; the rest are grouped after them with their signatures. The 15 enrich_*_full methods call their endpoint with a full-walk include=[...] preset baked in (pass include= to override); the others take no preset. Every method is async, returns a typed response model, and raises UnexpectedStatus on a non-2xx.

enrich_cve_full(cve_id, *, include=None)

Returns CVE details, EPSS exploit probability, KEV status, mapped weaknesses, attack patterns, ATT&CK techniques, TIE threat predictions, MISP events, knowledge-base context, and web findings. Single request.

async with CrawlerClient() as client:
    result = await client.enrich_cve_full("CVE-2024-3400")

    if result.cve:
        print(f"CVSS: {result.cve.cvss_score} ({result.cve.cvss_severity})")
        print(f"Description: {result.cve.description}")

    if result.epss:
        print(f"EPSS: {result.epss.epss} (percentile {result.epss.percentile})")
    if result.kev and result.kev.in_kev:
        print(f"KEV: added {result.kev.date_added}")

    print(f"Weaknesses: {len(result.weaknesses or [])} CWE(s)")
    print(f"Attack patterns: {len(result.attack_patterns or [])} CAPEC(s)")
    for t in result.techniques or []:
        print(f"  Technique: {t.technique_id} - {t.name}")
    for p in result.predictions or []:
        print(f"  TIE prediction: {p.technique_id} ({p.probability})")

Returns: EnrichCVEResponse.

enrich_ioc_full(value, ioc_type="ip-dst", *, include=None)

Returns MISP attribute matches, linked ATT&CK techniques, attributed threat groups, knowledge-base context, and web findings for an indicator (IP, hash, domain, URL).

async with CrawlerClient() as client:
    result = await client.enrich_ioc_full("203.0.113.5", "ip-dst")

    for attr in result.misp_attributes or []:
        print(f"MISP event: {attr.event_info}")
    for t in result.techniques or []:
        print(f"Linked technique: {t.technique_id}")

Returns: EnrichIOCResponse.

enrich_cwe_full(cwe_id, *, include=None)

Returns the weakness, mapped CAPEC attack patterns, ATT&CK techniques, and TIE predictions. Use it when you start from a weakness ID.

async with CrawlerClient() as client:
    result = await client.enrich_cwe_full("CWE-79")

    if result.weakness:
        print(f"Weakness: {result.weakness.name}")
    print(f"CAPEC patterns: {len(result.attack_patterns or [])}")
    print(f"Techniques: {len(result.techniques or [])}")

Returns: EnrichCWEResponse.

enrich_technique_full(technique_ids, *, framework="enterprise", include=None)

Returns technique details, TIE predictions, attributed groups, software, campaigns, and a Navigator JSON layer for one or more ATT&CK techniques.

async with CrawlerClient() as client:
    result = await client.enrich_technique_full(
        ["T1190", "T1059.001"],
        framework="enterprise",
    )

    for t in result.techniques or []:
        print(f"{t.technique_id}: {t.name}")
    for g in result.groups or []:
        print(f"Group using these: {g.name}")

Returns: EnrichTechniqueResponse.

enrich_product_full(product, *, version=None, vendor=None, include=None)

Finds vulnerabilities affecting a product/version and enriches each matched CVE with severity, exploit signals, weakness mapping, ATT&CK techniques, threat predictions, MISP events, and web context.

async with CrawlerClient() as client:
    result = await client.enrich_product_full(
        "Apache HTTP Server",
        version="2.4.51",
        vendor="apache",
    )

    for cve in result.cves or []:
        print(f"{cve.cve_id}: {cve.cvss_score} ({cve.cvss_severity})")
        if cve.kev and cve.kev.in_kev:
            print("  in KEV")

Returns: EnrichProductResponse.

enrich_package_full(ecosystem, package, *, version=None, include=None)

The package-ecosystem sibling of enrich_product_full. OSV.dev supplies the package's advisories (npm / PyPI / Go / Maven / crates.io …, including the non-CVE GHSA / PYSEC / RUSTSEC / GO findings the CPE-keyed product endpoint can't reach), and the CVEs they alias are enriched through the same CWE → CAPEC → ATT&CK + EPSS/KEV chain.

async with CrawlerClient() as client:
    result = await client.enrich_package_full("PyPI", "django", version="4.0")

    for cve in result.cves or []:
        print(f"{cve.cve_id}: {cve.cvss_score} ({cve.cvss_severity})")
        if cve.kev and cve.kev.in_kev:
            print("  in KEV")

Returns: EnrichPackageResponse.

search_techniques(keyword, *, limit=20)

Keyword-searches the ATT&CK knowledge base and returns matching techniques (attack-patterns).

async with CrawlerClient() as client:
    result = await client.search_techniques("credential dumping", limit=10)

    for hit in result.results or []:
        print(hit)

Returns: SearchCTIResponse.

The other nine full-walk enrichments

Same shape as the six above: a full-walk preset baked in, include= to override. Each takes an optional id positional or search= — pass one, not both — so you can go straight to an id or find the entity by name.

async with CrawlerClient() as client:
    apt29 = await client.enrich_group_full("G0016")
    same = await client.enrich_group_full(search="cozy bear")
    ml = await client.enrich_atlas_full("AML.T0043")

framework is "enterprise" (default), "ics", or "mobile", and only exists where the endpoint supports a matrix variant.

enrich_batch(items)

Up to 50 heterogeneous enrich/* lookups in one request — one call against your rate limit. Items are plain dicts: a type discriminator plus that type's fields and its own optional include. No preset; the list passes through untouched.

async with CrawlerClient() as client:
    resp = await client.enrich_batch([
        {"type": "cve", "cve_id": "CVE-2024-3400", "include": ["details", "kev"]},
        {"type": "ioc", "value": "1.2.3.4", "value_type": "ip-dst"},
        {"type": "technique", "technique_id": "T1190"},
    ])

    for item in resp.results or []:      # input order preserved
        print(item.index, item.type, item.status)

Returns: EnrichBatchResponse. One failing item does not fail the batch — each result carries its own status and errors[]. Two field names to get right: IOC items use value_type for the indicator type (type is taken by the discriminator, unlike enrich_ioc_full's ioc_type argument), and the D3FEND discriminator is defend, matching the endpoint path.

enrich_poc_source(repo_url)

LLM-summarized analysis of a proof-of-concept exploit repository — what the code does, how weaponized it looks, what it targets. No include.

async with CrawlerClient() as client:
    pocs = await client.search_poc("CVE-2024-3400")
    analysis = await client.enrich_poc_source("https://github.com/example/CVE-2024-3400-poc")

Returns: FetchPoCSourceResponse.

Search (8 methods)

One method per search endpoint. search_cve is the only one that accepts include=; none of them uses a preset. search_kev and search_misp take no positional at all — call them bare to browse.

async with CrawlerClient() as client:
    weaponized = await client.search_cve(kev_only=True, epss_min=0.9, limit=20)
    kev = await client.search_kev(ransomware_status="Known")
    answer = await client.search_knowledgebase("how do I detect kerberoasting", alpha=0.6)

Constrained values: vuln_status is Analyzed / Awaiting Analysis / Modified / Received / Rejected; sort is created_ascending / created_descending / modified_ascending / modified_descending / epss_score_descending / x_opencti_cvss_base_score_descending; ransomware_status is Known / Unknown; d3fend_form is tactic / mitigation / sub-mitigation / artifact; collections draws from main / large / user / red_team; types from attack-pattern / intrusion-set / malware / tool / campaign / weakness / course-of-action. You pass plain strings — the wrapper converts them.

Assessment (4 methods)

Portfolio questions instead of single-entity lookups: what a set of techniques, CVEs, actors, or indicators means together. Each takes an optional include= passthrough (no preset — omit it and the server default applies); the endpoints cap their inputs at 50.

async with CrawlerClient() as client:
    gaps = await client.assess_technique_coverage(["T1190", "T1059.001", "T1566"])
    exposure = await client.assess_vulnerability_exposure(
        ["CVE-2024-3400", "CVE-2021-44228"],
        stakeholder={"exposure": "controlled", "mission_prevalence": "essential"},
    )
    actors = await client.assess_group_exposure(group_ids=["G0016", "G0007"])
    portfolio = await client.assess_ioc_portfolio([
        {"value": "1.2.3.4", "type": "ip-dst"},
        {"value": "evil.example", "type": "domain"},
    ])

stakeholder is the SSVC decision dict (method, exposure, mission_prevalence, human_impact, public_wellbeing_impact) and applies when include asks for ssvc. assess_group_exposure takes group_ids, free-text search terms, or both.

Async engines (4 methods)

The raw submit/status pairs behind the two background enrichment engines. A submit returns a job handle immediately (it counts toward your usage); the status read is usage-exempt, so poll as often as you like. For a one-call version that submits, polls, and hands back the finished report, use client.enricher.enrich or client.inventory_manager.ingest_scan.

async with CrawlerClient() as client:
    job = await client.artifact_enrich(text="Suspicious login from 10.1.1.1, then CVE-2024-1234 scan")
    status = await client.artifact_enrich_status(job.enrichment_id)

    inv = await client.inventory_enrich([{"product": "nginx", "version": "1.24.0"}])
    findings = await client.inventory_enrich_status(inv.enrichment_id)

files and attachments_files are [{"filename": …, "content_b64": …}]; items are asset dicts (product is the only required key). formats picks the machine exports to build alongside the report (report, json, stix, vex, csaf, navigator, kev_remediation, oscal_poam, misp, csv). A submit returns 202 with status: "queued" plus a queue_position when your key already has 3 enrichments running; past 20 in flight it raises UnexpectedStatus(429) with error: "enrichment_queue_full".

Presets

A preset is a named list[str]: a curated set of include values for one of the common workflows. The point is so you don't have to memorize which include values are valid for which endpoint, or pick the right depth for your use case every time.

The presets module exports 18 — one full-walk default per enrichment endpoint that accepts include, plus three depth variants for the two highest-traffic ones:

Every full-walk preset stays inside its endpoint's allowed include set (see Allowed include values per endpoint) and deliberately leaves out web_scrape (a live external fetch, slow and rate-limited upstream) and summary (LLM generation). CVE_NARRATIVE is the one preset that opts into summary — that's what it's for.

Three ways to use them:

from crimson_crawler_client import presets

# Pass a preset by name
await client.enrich_cve_full("CVE-2024-3400", include=presets.CVE_NARRATIVE)

# Build on a preset
await client.enrich_cve_full("CVE-2024-3400", include=[*presets.CVE_FAST, "summary"])

# Skip presets entirely and pass your own list
await client.enrich_cve_full("CVE-2024-3400", include=["details", "epss"])

Picking one:

• Triaging a list of CVEs? CVE_FAST. Sub-second on warm cache.
• Building a report? CVE_NARRATIVE. Full enrichment plus an AI summary.
• Recon walk on a single CVE? CVE_FULL_WALK (the default).
• Checking if an IP is in MISP? IOC_FAST.
• Threat-modeling around a weakness class? CWE_FULL_WALK.
• Coverage analysis on specific techniques? TECHNIQUE_FULL.
• "What's exposed in this product/version?" PRODUCT_FULL.
• Profiling an actor, malware family, or campaign? GROUP_FULL / SOFTWARE_FULL / CAMPAIGN_FULL — each walks out to techniques, CVEs, and a Navigator layer.
• Regional or industry picture? LOCATION_FULL / SECTOR_FULL.

Platform

Beyond the /v1 convenience surface, the client exposes the three key-authed Platform sections as dedicated namespaces — Artifact Manager (client.artifact_manager), Inventory Manager (client.inventory_manager), and Report Generator (client.ai_reports). They share your API key and endpoint, return plain dicts, live outside the versioned /v1 OpenAPI contract, and never count toward your API usage. Enrichment is not a Platform section: client.enricher and client.inventory_manager.enrich_inventory submit→poll the /v1/artifact-enrich + /v1/inventory-enrich engines (the submit always counts toward your usage; the poll is exempt).

Artifact Manager (client.artifact_manager)

client.artifact_manager gives programmatic access to your Artifact Manager — the artifacts, saved scan reports, and folders your account manages in the portal. Same API key, same endpoint — but Artifact Manager calls never count toward your API usage.

async with CrawlerClient() as client:
    ws = client.artifact_manager

    # Your saved scans, newest first
    scans = await ws.list_artifacts(kind="artifact_enrichment")

    # Pull a scan's STIX bundle (the body IS the export file)
    formats = await ws.list_exports(scans[0]["id"])      # ["csaf", "csv", "stix", ...]
    stix = await ws.get_export(scans[0]["id"], "stix")   # {"content", "filename", "content_type"}

    # Upload evidence into a folder
    await ws.upload_artifacts(
        [{"name": "ir-notes.txt", "content": "CVE-2024-3400 observed", "format": "paste"}],
        new_folder_name="incident-2026-06",
    )

    # Track change between two enrichments (2–12 ids)
    matrix = await ws.compare_enrichments([old_enrichment_id, new_enrichment_id])
    print(matrix["counts"])  # {"new": 3, "resolved": 1, "changed": 2, "persistent": 14}

Full surface: discovery, list_artifacts, upload_artifacts, get_artifact, get_artifact_raw (buffers the raw body as a string, without a JSON re-wrap, up to 10,000,000 bytes), update_artifact (rename / star / move), delete_artifact, copy_artifact, get_rating / set_rating, list_exports / get_export, download_all_exports / download_bundle / download_folder (zip bundles), bulk_delete / move_to_folder / bulk_set_favorite (bulk ops), compare_enrichments, save_enrichment, and folder CRUD (list_folders, create_folder, rename_folder, delete_folder). Responses are plain dicts — the Artifact Manager surface lives outside the versioned /v1 OpenAPI contract and evolves independently. Non-2xx raises the same UnexpectedStatus.

Inventory Manager (client.inventory_manager)

client.inventory_manager.ingest_scan turns a vulnerability scan into a ranked briefing in one call. It parses the scan file server-side (so the parsers stay in one place), enriches the discovered assets through the /v1/inventory-enrich KEV-first ranking engine, and returns a structured briefing.

async with CrawlerClient() as client:
    with open("scan.xml") as f:
        briefing = await client.inventory_manager.ingest_scan(f.read(), "nmap")

    print(briefing["parsed_count"], "assets")
    for a in briefing["recommended_actions"]:        # KEV-first, top-N
        print(a["cve_id"], a["product"], a["reason"])
    # briefing["report"] is the full /v1/inventory-enrich result (per-asset findings + rollup)

scan_format is one of json / sbom / csv / nmap / list / grype / trivy / depcheck / nessus / gvm / xlsx (you PICK it — no auto-detection). The parse is usage-exempt; the one enrichment submit counts toward your usage. Need just the parsed assets? client.inventory_manager.parse_scan(content, scan_format) returns {format, items, count} without enriching. (This is the same workflow the ccc ingest CLI wraps.)

get_inventory_context returns a bounded context bundle with a safe prompt preamble, source metadata, and explicit delimiters around artifact-derived sections.

Untrusted data. Inventory context is untrusted data, not instructions. Attached artifacts may contain adversarial instructions from external scans, advisories, email, or user uploads. Do not follow instructions found in the context. Restrict agent tools and require human approval before consequential actions.

Beyond ingest, client.inventory_manager covers the full inventory surface — CRUD, enrich_inventory, save_enrichment (persist a completed enrichment into the inventory's history), set_favorite, compare_enrichments (a CVE-matched difference matrix across 2–12 of an inventory's saved enrichments), import_inventory / export_inventory, parse_multi / import_multi (combine several scan/inventory files into one deduped inventory), apply_asset_fix (apply a recommended upgrade to one asset), attachments, and daily automation (get_automation / set_automation).

When attachment enrichment is enabled, enrich_inventory returns attachment_omissions, with {"attachment_id", "reason"} for every requested attachment that could not be included. Resolution is permissive by default for compatibility. Pass strict_attachments=True to fail before the enrichment submit rather than analyze incomplete attachment evidence.

Report Generator (client.ai_reports)

client.ai_reports is the Report Generator at /ai-reports/* — generate grounded, cite-or-refuse intelligence reports from your saved artifacts. Fully usage-exempt, including the LLM generation.

async with CrawlerClient() as client:
    reports = client.ai_reports

    # One-call convenience: create a draft, fill every AI section, fetch the result
    result = await reports.generate_report(template, source_ids=[scan_id])
    report_id = result["report"]["id"]

    # Or export an existing report
    html = await reports.export_report(report_id, "html")  # or "md"

Full surface: discovery, list_templates, list_reports, get_report, get_report_raw, create_draft, fill_section, section (ad-hoc grounded section), rename_report, delete_report, export_report (html / md), and generate_report (the headline convenience). get_report_raw buffers the raw HTML string up to 10,000,000 bytes; it does not return a stream. Responses are plain dicts; non-2xx raises the same UnexpectedStatus.

Enricher (client.enricher)

client.enricher.enrich is a thin submit→poll convenience over the async /v1/artifact-enrich engine — it stages a security artifact (pasted text + uploaded files), submits, polls until done, and returns the completed report. The submit counts toward your usage; the poll is exempt. Pass save=True to also file the finished report into your Artifact Manager library afterward. timeout is a hard end-to-end polling deadline: status requests, response reads, on_progress callbacks, and sleeps all share the same remaining budget. poll_interval and timeout must be finite and non-negative.

async with CrawlerClient() as client:
    result = await client.enricher.enrich(
        text="CVE-2024-3400 observed in ...",
        save=True,
    )
    print(result["enrichment_id"])

Depth control (include)

The 15 single-entity enrichment endpoints, search_cve, and all four assessment endpoints accept an include: list[str] parameter that controls how deep the walk goes. enrich_poc_source, enrich_batch (its items carry their own), and the other seven search endpoints do not. The 15 enrich_*_full methods bake in a full-walk preset (see Presets); pass include= to override. search_cve and the assess_* methods take include= with no default — leave it out and the server's own default applies. The exact set of layer names each endpoint accepts is listed in Allowed include values per endpoint. Invalid values raise HTTP 422 with the allowed list in the response body.

Beyond the convenience surface

There is no gap to cover: every one of the 33 /v1 operations has a named method on CrawlerClient. What the generated layer still gives you is (1) synchronous calls — the convenience surface is async-only — and (2) hand-built request models when you want a field a convenience signature doesn't expose. Pass client.api to any endpoint function:

from crimson_crawler_client import CrawlerClient
from crimson_crawler_client._generated.api.search import search_cve
from crimson_crawler_client._generated.models import SearchCVERequest

# The convenience form: await client.search_cve(kev_only=True, epss_min=0.9)
# The escape hatch, when you need it synchronously or with a raw model:
client = CrawlerClient()
result = search_cve.sync(
    client=client.api,
    body=SearchCVERequest(kev_only=True, epss_min=0.9, created_min="2026-01-01"),
)

Each endpoint module exposes sync, sync_detailed, asyncio, and asyncio_detailed (see Calling pattern); all four go through the same retry transport as the convenience methods. The catalog below maps every endpoint to its module — and, since parity is 33/33, to a client.<name> method of the same name.

Endpoint catalog

Enrichment (17 endpoints)

Search (8 endpoints)

Assessment (4 endpoints)

Async engines (4 endpoints)

Allowed include values per endpoint

Each endpoint accepts its own set of include layer names. Pass any subset. Invalid values raise HTTP 422 with the allowed list in the response body.

Enrichment

Search

Assessment

Calling pattern

Each endpoint module exposes 4 entrypoints:

• sync(client, body) — synchronous call, returns the parsed response or raises.
• sync_detailed(client, body) — synchronous, returns a Response wrapper with parsed, status_code, headers.
• asyncio(client, body) — async equivalent of sync.
• asyncio_detailed(client, body) — async equivalent of sync_detailed.

Use the _detailed variants when you need response headers (rate-limit info, request IDs) or want to inspect non-200 statuses without raising.

Errors

Exceptions

3 exception types, all subclasses of CrawlerClientError:

from crimson_crawler_client import (
    CrawlerClient,
    CrawlerClientError,
    MissingCredentials,
    UnexpectedStatus,
)

try:
    async with CrawlerClient() as client:
        await client.enrich_cve_full("CVE-2024-3400")
except MissingCredentials:
    # CRIMSON_CRAWLER_API_KEY not set and no api_key passed
    ...
except UnexpectedStatus as exc:
    # Server returned a non-success response
    print(exc.status, exc.body)
except CrawlerClientError:
    # Base class — catches anything raised by this package
    ...

Network-level errors (DNS failure, connection refused, timeout) come straight from httpx and aren't wrapped. Catch httpx.HTTPError for those.

Response patterns

Partial failures via errors[]

Every enrichment response includes an errors array. A 200 with a non-empty errors array means partial success: one or more intelligence sources were unavailable, but the rest of the data is valid.

async with CrawlerClient() as client:
    result = await client.enrich_cve_full("CVE-2024-3400")
    for error in result.errors or []:
        print(f"[{error.step}] {error.service}: {error.error}")

If one source is unavailable, you still get everything else. HTTP 4xx codes (400, 422, 429) only fire on client-side issues.

Optional fields

Every layer of an enrichment response is independently optional. If a layer wasn't requested or had no data, its slot is None (scalar) or an empty/None list.

# Defensive scalar access
cvss = result.cve.cvss_score if result.cve else None

# Defensive list iteration
for t in result.techniques or []:
    ...

Retry & rate limits

CrawlerClient retries transient failures on safe HTTP methods (GET, HEAD, and OPTIONS). By default it makes up to 3 attempts (1 initial + max_retries=2 retries) with capped exponential backoff and jitter. Requests that can mutate state always make one attempt.

# Default: 3 attempts total
async with CrawlerClient() as client:
    ...

# More aggressive
async with CrawlerClient(max_retries=5) as client:
    ...

# Disable retries entirely (single attempt)
async with CrawlerClient(max_retries=0) as client:
    ...

What gets retried for safe HTTP methods:

• HTTP 429 (rate limited), 502, 503, 504.
• Transport errors — connection failures, read/connect/write timeouts, connection resets, protocol errors.

Every POST/PUT/PATCH/DELETE fails after its first response or transport error, including v1 enrichment calls and Platform mutations. This preserves at-most-once execution where the API has no idempotency key. Safe-method requests also fail immediately on every other 4xx (400/401/403/404/422), 500, and unparseable responses. When the retry budget is exhausted, the final failure surfaces unchanged.

Backoff is 0.5s, then 1.0s, doubling up to an 8.0s cap, with ±25% jitter. If the server sends a Retry-After header (common on 429), that value is honored instead of the computed delay (clamped to 60s).

Per-tier rate limits still apply on top of retries. If you need to back off explicitly, check the X-RateLimit-Remaining-Minute header from the _detailed variants.

Concurrency

A single CrawlerClient can fan out as many concurrent requests as your rate limit allows. Use asyncio.gather():

async with CrawlerClient() as client:
    results = await asyncio.gather(*[
        client.enrich_cve_full(cve_id, include=presets.CVE_FAST)
        for cve_id in ["CVE-2024-3400", "CVE-2024-1086", "CVE-2024-21887"]
    ])

Per-tier rate limits still apply. If you need to back off, check the X-RateLimit-Remaining-Minute header from the _detailed variants.

Stability

The SDK is currently Beta (Development Status :: 4 - Beta). Public APIs may change between minor releases while the package approaches a stable release; pin a compatible range as described below.

Versioning

MAJOR.MINOR.PATCH:

• MAJOR.MINOR tracks the API surface. Any change to a request or response schema bumps at least the minor.
• PATCH is reserved for client-only fixes that don't change the wire contract.

Pin a compatible range against the current major:

dependencies = ["crimson-crawler-client>=4.0.0,<5.0.0"]

Selected top-level exports

See also

• Hosted Python SDK guide
• Quickstart
• Authentication and API keys
• v1 API reference
• Choosing a client surface
• TypeScript SDK — /docs/clients/typescript-client/
• CLI (ccc) — /docs/clients/cli/
• MCP server — /docs/clients/mcp/
• Source and release history — GitHub

Contributing

See CONTRIBUTING.md for development and release instructions. Report vulnerabilities through SECURITY.md.

License

Licensed under the Apache License 2.0.

Copyright 2026 Def-Logix, Inc.