Developer API

Automate AI Commerce Readiness without exposing workspace secrets.

Use CatalogWise API keys to run scans, read product evidence, generate reports and track credits for Scale and Agency workflows. Examples use placeholders only.

Manage API keys Open product docs

Authentication

Create keys in the dashboard. The secret is shown once, stored as a hash, and can be revoked at any time.

curl https://catalogwise.com/api/v1/scans \
  -H "Authorization: Bearer cw_live_<shown_once_secret>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example-store.com","consent":true}'

Never put API keys in client code, screenshots or browser-exposed environment variables.

Scopes

scans:read

Read scan history and scan result metadata.

scans:write

Create new public scans for the workspace.

reports:read

Read report metadata and report status.

reports:write

Generate reports and report export actions.

usage:read

Read credit balance, reservations and usage events.

tools:run

Run eligible diagnostic tools through API workflows.

Endpoints and Credit Costs

Method	Path	Purpose	Credits
GET	/api/health	Platform health and provider status	0
POST	/api/v1/scans	Create a public catalog readiness scan	10
GET	/api/v1/scans	List scans for the authenticated workspace	0
GET	/api/v1/products	List product evidence from persisted scans	0
GET	/api/v1/issues	List findings and issue evidence	0
GET	/api/v1/recommendations	List recommended fixes and priorities	0
GET	/api/v1/reports	List generated reports	0
POST	/api/reports/generate	Generate an evidence-backed report	150
POST	/api/reports/{id}/export	Download a branded PDF report	0 after report
GET	/api/v1/usage	Read credits, usage and reset state	0

Response Envelope

{
  "ok": true,
  "data": {
    "scanId": "scan_placeholder",
    "sourceType": "public_quick_scan"
  },
  "meta": {
    "evidenceCount": 18,
    "credits": { "reserved": 10, "consumed": 10 }
  }
}

Error Envelope

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A valid API key is required.",
    "referenceId": "cw_ref_123"
  }
}

Rate Limits

Scan, tool, lead, checkout and chat routes are rate limited. Build clients to retry after `RATE_LIMITED` responses with backoff.

Idempotency keys are supported on scan and checkout workflows where available.

Versioning

Stable API routes use `/api/v1`. Breaking changes will ship under a new version with a documented migration window.

Current changelog: v1 supports scans, products, issues, recommendations, reports and usage.

Sample Integration Workflow

Create scoped key

Use the dashboard to create a named key and copy it once.

Run scan

POST a public store URL with consent and an idempotency key.

Read evidence

Fetch products, issues and recommendations for the workspace.

Generate report

Create a report when enough evidence exists and track credits.

Webhooks

Webhook settings are managed from `/dashboard/api` when enabled. If webhook delivery needs setup, the dashboard shows a configuration-required state instead of pretending delivery is active. Signing secrets are generated server-side and should be treated like API keys.

scan.completedscan.failedreport.readyreport.sharedreport.share_revokedcredits.consumedcredits.refundedapi_key.createdapi_key.revoked