Reference clients

client.capabilities()       # 1 discover
client.search(              # 2 bound
    limit=100, max_units=100,
    idempotency_key=key,
)                           # 3 request
validate(response)          # 4 accept

await client.capabilities() // 1 discover
await client.search({       // 2 bound
  limit: 100, max_units: 100,
  idempotencyKey: key,
})                           // 3 request
validate(response)           // 4 accept

CleanedWeb publishes small dependency-free reference clients rather than claiming a mature language SDK surface:

• Python: https://cleanedweb.com/examples/cleanedweb_client.py
• TypeScript-compatible ESM: https://cleanedweb.com/examples/cleanedweb-client.ts

Choose a client

Use the Python reference client for Python services and notebooks. Use the TypeScript-compatible client for trusted Node.js or server-side JavaScript applications. Do not put either client or a workspace API key in public browser code.

These files are intentionally readable implementations. They demonstrate the contract but do not promise the release cadence, platform support, dependency management, or semantic versioning of a supported SDK.

Shared request sequence

Both clients:

• read live capabilities before machine access;
• keep the Bearer key in the trusted process;
• require limit, max_units, and an idempotency key;
• validate count, schema, canonical-ID uniqueness, and truncation;
• preserve the untouched structured response and usage receipt;
• surface stable API failures rather than converting them to empty results.

The safe sequence is the same in both languages: read capabilities, verify machine access, confirm the market, resolve ambiguous locations, set limit and max_units, attach an idempotency key, send the request, validate the response, persist it, and retain the receipt.

Supported operations

They expose capabilities, entitled markets, location suggestions, bounded search, current canonical property retrieval, and finalized property changes. They deliberately omit account administration, saved-search mutation, destination management, and generic HTTP.

Production boundary

They are examples, not a semantic substitute for capabilities, OpenAPI, JSON Schemas, Arazzo, or the error guide. Copy them into an application only with explicit timeout, logging, freshness, secret-management, and retry policies appropriate for that environment.

Before production use, review security and authentication, follow the deterministic workflows, implement the error policy, and retain the operational evidence defined in operations and reliability.