# Reference clients

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](/examples/cleanedweb_client.py) for Python services and
notebooks. Use the [TypeScript-compatible client](/examples/cleanedweb-client.ts) 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.

| Operation | Python | TypeScript | Contract authority |
| --- | --- | --- | --- |
| Capabilities | Included | Included | Runtime capabilities |
| Markets and locations | Included | Included | OpenAPI response |
| Bounded property search | Included | Included | OpenAPI, schema and receipt |
| Property and changes | Included | Included | OpenAPI and schema |
| Account administration | Omitted | Omitted | Portal only |

## 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](/docs/security/), follow the
[deterministic workflows](/docs/workflows/), implement the [error policy](/docs/errors/), and
retain the operational evidence defined in [operations and reliability](/docs/operations/).