Your first API request
Start with an API you have built and tested in your workspace. It gives you what you need to call it: the source ID, the saved version, the output fields, the limits, and a request to copy.
On this page
1. Inspect and build#
Enter a public collection URL in the API generator and select Explore source. If the website has several collections, choose one under Choose a collection to inspect. All observed fields are included; review the sample records before continuing.
Signed out, select Run a test, then Access console to sign up and save the API. Signed in, select Create this API; once the build is validated, use Run a test or Copy request. A preview or a build still in progress is not an accepted API.
Compare the output schema and sample records with your intended use; different sources can support different inputs. The fictional table-lamp example shows how to move from a collection URL through reviewed fields to an accepted contract.
2. Prepare your server#
Copy the exact API base URL and request example supplied by your workspace. When machine access is available, create an API key and keep it in your server’s secret storage. Never embed it in browser JavaScript.
Set these values in your server environment before running the example:
| Variable | Value |
|---|---|
CLEANEDWEB_API_BASE |
https://api.cleanedweb.com, the API origin, without a path. |
CLEANEDWEB_SOURCE_ID |
Saved source identifier. |
CLEANEDWEB_DEFINITION_VERSION |
The saved version of your API: a 64-character lowercase string. |
CLEANEDWEB_API_KEY |
Server credential with run access to this API. |
CLEANEDWEB_IDEMPOTENCY_KEY |
Unique key saved with this intended request before sending. |
For the request key, use a UUID or 1–200 letters, numbers, ., _, :, or -. Save it alongside the source, version, and inputs. Reuse it only to recover the same request; choose a new key for a new execution. The API origin is https://api.cleanedweb.com, not a source website URL.
3. Make a bounded request#
This request stops after at most 25 records (max_items). A run also ends when timeout_seconds (default 10800) passes or the workspace balance or monthly usage budget runs out. On newer APIs with detail pages, enrich_records defaults to true; send "input":{"enrich_records":false} to read list pages only. Use the input your API's generated request example publishes. It executes the source and may incur usage. Search APIs can require a constrained query instead; follow the generated request when its contract differs.
umask 077
: "${CLEANEDWEB_IDEMPOTENCY_KEY:?Set the saved key for this request}"
curl --fail-with-body --max-time 120 \
"${CLEANEDWEB_API_BASE}/v1/sources/${CLEANEDWEB_SOURCE_ID}/run" \
-H "Authorization: Bearer ${CLEANEDWEB_API_KEY}" \
-H "Idempotency-Key: ${CLEANEDWEB_IDEMPOTENCY_KEY}" \
-H 'Content-Type: application/json' \
--data "{\"expected_version\":\"${CLEANEDWEB_DEFINITION_VERSION}\",\"input\":{},\"max_items\":25}"
The API waits up to 90 seconds for the run to end. If it answers 202, the body is a run object, not records: the run continues. Read GET /v1/runs/{run_id}/result (links.result) after Retry-After seconds until it returns 200 or an error, rather than resending the POST. See the Run API reference.
expected_version requires the active source definition to match your saved version. If it has changed, inspect the new definition and schema before updating your integration. Do not remove the version check merely to get past a conflict.
4. Inspect the result#
Read records together with summary, not on their own. A shortened, illustrative response might look like this; use the fields and version returned by your API rather than copying these values:
{
"records": [{ "name": "Arc table lamp", "price": 48 }],
"summary": {
"status": "bounded",
"within_scope_passed": true,
"catalog_complete": false
}
}
The shortened example omits version and delivery fields. In the full response, require both summary.definition_version and metadata.definition_version to equal CLEANEDWEB_DEFINITION_VERSION. Check summary.within_scope_passed, summary.status, and run.stop_reason. In this example, the request satisfied its selected boundary; it did not establish full-catalog coverage. A partial status or within_scope_passed: false needs review even when records were returned. See pagination and output before increasing limits.
Keep delivery.runId and traceId where returned; delivery.chargeReceiptId is the same identifier as the run ID. Do not treat HTTP 200, a nonempty array, or a successful build as proof that all source records were collected. If the connection times out, keep the saved request key and follow idempotency and recovery before retrying.
5. Integrate carefully#
Store only the data you need, validate fields before downstream use, and preserve missing values rather than inventing them. See the Run API reference, authentication and limits, and errors and retries before scheduling recurring runs.