How to use — API — commonspecs

Install the skill in your agent and add the recommended MCP connection.
The API tab documents the raw endpoints.

Base URL https://api.commonspecs.com.

Authentication

Send the bearer token in a header:

Authorization: Bearer cs_live_…

POST /v1/get_product

Resolve one product or service by exactly one key: id, url or ean.

curl -X POST https://api.commonspecs.com/v1/get_product \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ean":"<EAN/GTIN>"}'

POST /v1/search_products

query searches by brand, item name or category name — products and services alike. category browses one category by its identifier. Category identifiers come back in matched_categories (a hit) or did_you_mean (a miss). filters narrow the results by the traits recorded in the specification and require a category. Ten results per page. page gets the next ones.

curl -X POST https://api.commonspecs.com/v1/search_products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"<brand or product name>","category":"<identifier from matched_categories>"}'

POST /v1/compare_products

Compare up to 5 items side by side. product_ids takes the id that every search or lookup result carries, so resolve each item first with search_products or get_product and pass the ids you got back. Anything not in the catalogue yet has no id; contribute it first.

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

POST /v1/submit_contribution

Submit verified specs (fields) and/or a dated price observation (offer) — at least one of the two. Identify the product or service as in lookup. Passing brand together with name creates a new catalogue entry when no such item exists yet. When you read the values off a page, give each field its source_url and the verbatim snippet. When you read them off the product itself — a label or the packaging — pass "source": "label" and skip both.

curl -X POST https://api.commonspecs.com/v1/submit_contribution \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "brand":"<brand>","name":"<product name>","source":"web",
    "fields":[{"field_name":"<schema field>","value":"<value as printed>",
      "source_url":"https://…","snippet":"<verbatim text>"}],
    "offer":{"store":"<shop domain>","country":"<ISO 3166-1>","price":<number>,
      "currency":"<ISO 4217>","availability":"in_stock","source_url":"https://…"}
  }'

POST /v1/flag_stale

Flag a fact or price that looks stale, wrong, or disputed. It records the report for review and never changes the product itself. field_name and reason are optional.