Integration documentation

From a property question
to a trusted result.

One public contract for people, applications, and AI agents. Discover live capabilities, search maintained property snapshots, preserve provenance, and keep every machine request inside an explicit Unit budget.

Start with the API Connect an agent

Runtime truth comes first

GET /v1/capabilities

Check this endpoint before every integration path. Use API keys or MCP only when machine_access.enabled is true. Static docs do not override the live manifest.

Open capabilities ↗

For people

Use the console

Explore markets, search, save, and inspect usage without code.

For applications

Call the REST API

Use stable schemas, bounded requests, and durable receipts.

For AI systems

Connect through MCP

Expose five workspace-scoped tools with typed output and explicit Unit boundaries.

Integration architecture

Discover first. Bound the request. Accept the delivery.

Every integration path follows the same operating contract, whether the caller is a person, application, or agent.

Choose your responsibility

The shortest path to the contract you own.

Developers

Build the first bounded request.

AI agents

Discover runtime truth before tool use.

Operations

Recover without hiding partial delivery.

Security

Inspect credentials and trust boundaries.

For people5 minutes

Start in the workspace console.

The console is the fastest way to confirm access and learn the data shape. It uses your signed-in workspace session and shows only entitled, ready markets.

1
Sign in.
Open the console with your workspace account.
Sign in ↗
2
Confirm runtime access.
Check that the workspace, market, and Search status are active.
3
Run a narrow search.
Inspect canonical IDs, sources, snapshot time, and Unit receipt before automating.
4
Create a machine key when enabled.
Open API keys, name the credential, and copy its one-time secret into a secret manager.

Credential boundary

Browser requests use the signed-in session. Server applications use a workspace Bearer key only when runtime machine access is enabled. Never put cookies or API-key secrets in prompts, URLs, logs, or client-side code.

REST APIQuickstart

Discover, then search.

The manifest is public and uncached. Read it before constructing a request so your client uses the current market list, filters, limits, schemas, and Unit costs.

Step 1

Read live capabilities

Do not replace a failed manifest request with an empty market list.

curl --fail-with-body --silent --show-error \
  https://app.cleanedweb.com/v1/capabilities

Step 2

Keep the key outside your code

Create it in the console and inject it from a server-side secret manager.

export CLEANEDWEB_API_KEY="cw_live_…"

Step 3

Send a bounded search

A machine search requires limit, max_units, and an idempotency key.

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer ${CLEANEDWEB_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: search-lu-belair-001" \
  --data '{
    "market": "LU",
    "response_schema": "property-profile-v2",
    "deal_type": ["buy"],
    "property_categories": ["apartment"],
    "limit": 100,
    "max_units": 100
  }' \
  https://app.cleanedweb.com/v1/properties/search

Authoritative operationsOpenAPI JSON ↗ Copyable payloadSearch example ↗

Result safetyRequired checks

A 200 response is only the beginning.

Accept a property snapshot only after its identity, count, freshness, and completeness checks pass. Preserve source provenance beside every canonical record.

Envelope

returned === results.length

Schema

Every row is property-profile-v2.

Identity

Every property_entity_id is present and unique.

Freshness

snapshot.dataUpdatedAt passes your policy.

Completeness

Follow next_cursor until has_more is false.

Receipt

Persist request ID, Units, balance, and usage classification.

AI agentsMCP 2025-11-25

Give agents narrow tools, not raw access.

When the runtime gate is enabled, connect a trusted MCP client to the stateless Streamable HTTP endpoint. The client owns the Bearer key; it must never become a prompt, tool argument, tool result, URL, or trace.

cleanedweb_capabilitiesDiscover runtime truthFree read

cleanedweb_list_marketsList entitled, ready marketsFree read

cleanedweb_search_propertiesSearch a bounded snapshotMetered

cleanedweb_get_propertyRead one canonical propertyFree read

cleanedweb_list_property_changesRead finalized changesFree read

Agent handoff

Give the model an index. Keep secrets in the adapter.

Start with the compact index for discovery. Use the consolidated file when the agent needs the complete contract, then validate actual calls against OpenAPI and the runtime manifest.

Operational safetyUnits and retries

Budget every delivery. Retry without paying twice.

Unit ceiling

Read unit_costs from capabilities and set max_units on every machine search. An empty Unit-cost object means machine charging is not ready; do not estimate a price from marketing copy.

Durable idempotency

Retry the exact request with the same key. A matching retry returns its stored receipt without another charge. Reusing the key for a changed request returns idempotency_conflict.

Rate limits

A shared key limit returns 429 with Retry-After. Wait, keep the same idempotency key, and do not spread retries across processes.

Availability

Retry 503 with bounded exponential backoff and jitter. Never turn an availability failure into an empty result set or empty capability manifest.

EnterpriseContract + operations

Evaluate the boundary, not a sales claim.

Review field semantics, credential isolation, compatibility rules, operational recovery, deterministic workflows, and explicit non-guarantees in one implementation-facing contract.

Human guideEnterprise contract

Modern overview of semantics, security, lifecycle, operations, and trust boundaries.

DataProperty profile field catalog v2

Machine-readable meanings, units, omission policy, identity, and provenance.

WorkflowArazzo

Deterministic bounded-search and property-history procedures.

EventsAsyncAPI

Signed webhook messages, headers, duplicate behavior, and retry contract.

LifecycleMachine changelog

Current contract additions, clarifications, and breaking-change markers.

CodeReference clients

Dependency-free Python and TypeScript-compatible safe integration examples.

ReferenceAuthoritative files

Build against contracts, not examples alone.

MethodData methodology

Coverage, normalization, identity, provenance, freshness, and delivery acceptance.

GuidesProperty data engineering

Human-readable guides to canonical identity, deduplication, change tracking, and API evaluation.

RuntimeCapabilities manifest

Markets, filters, versions, limits, Unit costs, and machine gate.

HTTPOpenAPI contract

Authoritative property operations, parameters, and responses.

SchemaGlobal property profile v2

Canonical property identity, grouped listings, history, context, and provenance.

CatalogProperty profile semantics v2

Units, missing-value behavior, identity, and provenance boundaries.

SchemaProperty event v1

Finalized observed change structure.

DeliveryWebhook guide

Event envelopes, signature verification, deduplication, and retries.

RecoveryError guide

Stable codes, retry boundaries, and safe agent behavior.