Work with the evidence.

BEFORE YOU CONNECT

Access & authentication

Every API request requires an active internal_access grant, plus an authorized browser session or a bearer API key owned by a user with that grant. Signing in or subscribing to Pro does not grant API access.

There is no public, self-service key issuance. After access is approved, authorized users can manage their own keys in the protected reference. Keys inherit the owner’s current access; revoking the grant disables those keys.

Keep your key in a local environment variable or server-side secret store. Do not include it in browser code, shared reports, or source control.

READ STORED DATA

Your first query

The API base is https://chatadswatch.com/api/v1. These shell examples use an existing approved key in CAW_API_KEY. They only read stored records.

BASE="https://chatadswatch.com"
# Set CAW_API_KEY to your approved key in your local environment.

curl "$BASE/api/v1/capabilities" \
  -H "Authorization: Bearer $CAW_API_KEY"

curl "$BASE/api/v1/ads?q=warehouse&search_in=prompts&limit=20&sort=last_seen" \
  -H "Authorization: Bearer $CAW_API_KEY"

The second request returns ads associated with prompts containing “warehouse,” ordered by the source’s last-seen date. Search matches recorded text; it does not identify the advertiser’s targeting settings.

API V1

Available resources

Ads, advertisers, prompts, and landing pages also support /{id} reads. Detail responses use a one-element data array. Relationships describe captured records, not complete conversations or campaign structures.

MAKE RESULTS REPRODUCIBLE

Filters & pagination

• q searches up to eight words, with all words required to match. search_in selects ads, advertisers, or prompts, separated by commas. The prompts resource searches prompt text only.
• Use exact values for domain, industry, advertiser_industry, topic, and intent. Read /taxonomies for supported labels. Advertiser industry and advertised product industry are separate fields.
• country accepts an uppercase two-letter country code or unknown. Unknown records are excluded from a specific-country query.
• last_seen_from and last_seen_to accept inclusive YYYY-MM-DD dates. They filter the source’s last-observed date.

Lists default to 50 records and accept limit from 1 to 100. Follow meta.next_cursor as the next request’s URL-encoded cursor, keeping every other query parameter unchanged. A null cursor marks the end.

If the catalog changes, pagination returns 409; restart without the cursor. Historical catalog versions are not archived. Retain returned records and their metadata when you need to reproduce a report.

Read meta alongside data: catalog version, methodology, evidence type, and count semantics are part of the result. Missing metrics remain null, and captured appearances are not impressions or spend.

WEBSITE DATA

Read an existing snapshot

Website endpoints follow /sites/{domain}/{resource}. Resources include profile, traffic, related-sites, search reports, backlinks/summary, and shopping/ads.

# Read an existing worldwide traffic snapshot.
curl "$BASE/api/v1/sites/example.com/traffic?market=worldwide" \
  -H "Authorization: Bearer $CAW_API_KEY"

# Read an existing paid-keyword snapshot for the US market.
curl "$BASE/api/v1/sites/example.com/search/keywords?market=US&mode=paid" \
  -H "Authorization: Bearer $CAW_API_KEY"

example.com is a placeholder domain; these examples do not promise that a snapshot exists. A response with meta.status: not_collected means no matching stored snapshot is available.

Profile, traffic, related sites, and backlinks support worldwide scope. Search resources support US, GB, CA, and AU. Keyword reads require mode=organic or mode=paid; search competitors support paid mode only.

Inspect collection time, scope, evidence type, and stale. Use a returned snapshot_id to pin an immutable result. Search results are bounded samples, and missing results do not prove zero activity.

HANDLE THE RESPONSE

Errors & limits

Errors include a safe message, a machine-readable code, and a request_id. Keep the request ID when investigating a failed call.

The documented limits are 120 reads and 6 new collections per minute per internal user. Use /capabilities and the protected OpenAPI specification to check the current contract.