API reference

Base URL https://api.commonspecs.com. All /v1 endpoints require an API token. JSON in, JSON out.

Authentication

Send your token as a bearer header (or X-API-Token):

Authorization: Bearer cs_live_…

Requests must arrive through the edge; the origin rejects direct traffic. Missing/invalid token → 401.

POST /v1/lookup

Resolve one product by exactly one of url, ean, or brand + model.

curl -X POST https://api.commonspecs.com/v1/lookup \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"brand":"Nudie","model":"Gritty Jackson"}'

status is hit, candidates (several variants matched), or miss. A hit returns product, quality_score (0–100 or null), fields, low_confidence_fields, and enrichment_opportunities. Each field has value, confidence, disputed, needs_corroboration, and (when disputed) alternate_claims. Optional: exclude_low_confidence: true.

POST /v1/search

Match products by brand/model, ranked by quality score (best first). Up to 20 results.

curl -X POST https://api.commonspecs.com/v1/search \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"raw denim","category":"jeans-denim","limit":10}'

Returns { count, results: [{ …product, quality_score }] }.

POST /v1/compare

Compare up to 5 products side by side.

curl -X POST https://api.commonspecs.com/v1/compare \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_ids":["…","…"]}'

Returns products (each with quality_score), a comparison matrix ([{ field, cells: { product_id: { value, confidence } | null } }]), and overall_winner (the highest-scoring product id). Per-dimension winners and a rationale are deliberately not returned — reason about the trade-off from the facts.

GET /v1/products/{id}

Fetch one product with its banded fields. Append ?exclude_low_confidence=true to drop the low bucket.

curl https://api.commonspecs.com/v1/products/$ID -H "Authorization: Bearer $TOKEN"

GET /v1/products/{id}/quality-score

The product's total_score (0–100, or null if the category isn't scored) and missing_fields.

curl https://api.commonspecs.com/v1/products/$ID/quality-score -H "Authorization: Bearer $TOKEN"

GET /v1/categories/{slug}/rankings

Top products in a category by quality score. ?country=PL&limit=20 (limit ≤ 100).

curl "https://api.commonspecs.com/v1/categories/jeans-denim/rankings?limit=20" \
  -H "Authorization: Bearer $TOKEN"

ranking_scope is currently global; a requested country_code is echoed but the ranking is the global score order until pricing/availability lands.

POST /v1/contributions

Submit verified specs. Identify the product as in lookup; brand+model creates it if new. Each field should carry the source_url and the verbatim snippet you read it from — that evidence earns confidence.

curl -X POST https://api.commonspecs.com/v1/contributions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "brand":"Nudie Jeans","model":"Gritty Jackson","source":"web",
    "fields":[{"field_name":"fabric_weight","value":"13.5 oz",
      "source_url":"https://…","snippet":"13.5 oz organic dry denim"}]
  }'

Errors

Errors are JSON: { "error": { "code", "message" } }. Common codes: 400 invalid_request, 401 unauthorized, 403 forbidden, 404 not_found. Internal-only fields (reputation, dimension scores, scoring rules) are never present in any response.

Easiest path: let the reference skill make these calls for you.