Python and JavaScript clients

Typed, zero-runtime-dependency clients for applications that call the Scorch HTTP API directly.

The source packages currently install from the repository and are not yet published to PyPI or npm. Their versions follow Scorch's API version.

Python

The Python package supports Python 3.11 and newer. It is synchronous, fully typed, and uses only the standard library.

python -m pip install ./clients/python

from scorch_client import ScorchClient

client = ScorchClient()
response = client.search(
    "Rust HTTP clients",
    categories=["github"],
    engines=["brave-web", "crates-io", "npm", "yahoo"],
    limit=5,
)

for result in response["results"]:
    print(result["title"], result["url"])

page = client.scrape(
    "https://example.com",
    options={"formats": ["markdown", "links"]},
)
print(page.get("markdown", ""))

Request parameters use Python-style names while returned dictionaries preserve the HTTP API's camel-case field names.

JavaScript and TypeScript

The ESM package supports Node.js 22 and modern Fetch API runtimes. It ships TypeScript declarations and has no runtime dependencies.

npm install ./clients/javascript

import { ScorchClient } from "@fractal-tess/scorch";

const client = new ScorchClient();
const response = await client.search("Rust HTTP clients", {
  categories: ["github"],
  engines: ["brave-web", "crates-io", "npm", "yahoo"],
  limit: 5,
});

for (const result of response.results) {
  console.log(result.title, result.url);
}

const page = await client.scrape("https://example.com", {
  formats: ["markdown", "links"],
});

Every JavaScript operation accepts a final { signal } argument for cancellation with AbortController.

Operations

HTTP operation	Python	JavaScript
Health	`health`	`health`
Readiness	`readiness`	`readiness`
Search	`search`	`search`
Scrape	`scrape`	`scrape`
Map	`map`	`map`
Start crawl	`start_crawl`	`startCrawl`
Crawl status	`crawl_status`	`crawlStatus`
Cancel crawl	`cancel_crawl`	`cancelCrawl`

Gateways, errors, and limits

Both clients default to http://127.0.0.1:33000, honor SCORCH_API_URL in their server runtimes, and accept static headers for an authenticated gateway. Credentials embedded in the base URL are rejected. API redirects are not followed, so gateway headers are never forwarded to another origin.

# Python
client = ScorchClient(
    "https://scorch.example.com",
    headers={"Authorization": "Bearer ..."},
)

// JavaScript
const client = new ScorchClient({
  baseUrl: "https://scorch.example.com",
  headers: { Authorization: "Bearer ..." },
});

Structured API errors expose the HTTP status, Scorch error code, message, and request ID. Connection failures and invalid responses use separate exception classes. Response bodies are streamed into a bounded 64 MiB buffer by default.