Jak używać — API — commonspecs

Zainstaluj w swoim agencie skill i dodaj zalecane połączenie MCP.
Zakładka API opisuje surowe endpointy.

Bazowy adres URL https://api.commonspecs.com. Wszystkie endpointy /v1 wymagają tokenu API. JSON na wejściu, JSON na wyjściu. Każda odpowiedź odczytu niesie też blok context — user_goal (Twoje zapisane cele zakupowe jako gotowa do zastosowania dyrektywa), user_market, contribution_mode — rozwiązany po stronie serwera z preferencji konta.

Uwierzytelnianie

Wyślij token w nagłówku bearer (lub X-API-Token):

Authorization: Bearer cs_live_…

Żądania muszą trafiać przez warstwę brzegową; origin odrzuca ruch bezpośredni. Brak/nieprawidłowy token → 401.

POST /v1/get_product

Rozpoznaj jeden produkt po dokładnie jednym z: id, url, ean albo brand + model.

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

status to hit, candidates (dopasowano kilka wariantów) albo miss. Trafienie zwraca product, missing_fields, listę offers (wycenioną dla rynku kupującego, najlepsza oferta pierwsza — najniższa cena z dostawą, złagodzona świeżością), fields, low_confidence_fields oraz enrichment_opportunities. Każde pole ma value, confidence, disputed, needs_corroboration oraz (gdy sporne) alternate_claims. Pola o niskiej pewności zawsze jadą w osobnym koszyku — enrichment_opportunities wskazuje, co potwierdzić.

POST /v1/search_products

Znajdź produkty przez query i/lub przeglądaj category (sama kategoria zwraca jej ranking), uszeregowane wg wyniku jakości (najlepsze pierwsze). Stronicowane: page, page_size (domyślnie 10, ≤ 20).

curl -X POST https://api.commonspecs.com/v1/search_products \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"<brand, model, or need>","category":"<slug from a prior response>","page_size":10}'

Zwraca { count, page, page_size, has_more, results: [product] }, najlepsze pierwsze — kolejność jest jedynym sygnałem jakości; żaden wynik liczbowy nie jest zwracany. Trafienie niesie też matched_categories; pudło niesie did_you_mean. Wyniki preferują produkty z potwierdzoną ofertą na Twoim rynku; gdy żaden jej nie ma, ci sami kandydaci wracają w rankingu specyfikacji z flagą availability: "unconfirmed" — dostępność tam nadal wymaga sprawdzenia.

POST /v1/compare_products

Porównaj do 5 produktów obok siebie.

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

Zwraca products uszeregowane od najlepiej udokumentowanego (products[0] to zwycięzca — nie ma osobnego pola z werdyktem) oraz macierz comparison ([{ field, cells: { product_id: { value, confidence } | null } }]). Wyniki punktowe, zwycięzcy w poszczególnych wymiarach ani uzasadnienie nie są celowo zwracane — wyciągnij wnioski o kompromisie z samych faktów.

POST /v1/submit_contribution

Zgłoś zweryfikowane specyfikacje (fields) i/lub datowaną obserwację ceny (offer) — co najmniej jedno z dwojga. Zidentyfikuj produkt jak w lookup; brand+model tworzy go, jeśli jest nowy. Każde pole powinno nieść source_url oraz dosłowny snippet, z którego je odczytałeś — ten dowód buduje pewność. Cena nigdy nie idzie w fields; cena to offer.

curl -X POST https://api.commonspecs.com/v1/submit_contribution \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "brand":"<brand>","model":"<model>","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

Zgłoś fakt lub cenę, które wyglądają na nieaktualne, błędne lub sporne. Zapisuje sygnał do przeglądu kuratorskiego — nigdy nie zmienia produktu. field_name i reason są opcjonalne.

curl -X POST https://api.commonspecs.com/v1/flag_stale \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_id":"…","field_name":"<schema field>","reason":"<what looks wrong and what you saw>"}'

Endpointy konta

GET /v1/categories/{slug}/schema — publiczny kształt pól rozpoznanej kategorii (nazwy, jednostki, typy); wagi punktacji nie są ujawniane. Pełnej listy kategorii nie ma — slugi odkrywasz przez matched_categories / did_you_mean z wyszukiwania.
GET /v1/tokens · POST /v1/tokens · DELETE /v1/tokens/{id} — Twoje tokeny API: lista (tylko prefiks i metadane), wydanie (jawna wartość zwracana jeden raz), unieważnienie.
GET /v1/usage — zużycie na Twoim koncie: plan, aktywne tokeny, dzisiejsze zgłoszenia względem dziennego limitu, łączna liczba kontrybucji.
GET /v1/user/preferences · PUT /v1/user/preferences — odczyt i zmiana preferencji zakupowych, które serwer stosuje przy każdym odczycie (rynek, strategia jakości/lokalności, tryb kontrybucji, język).

Błędy

Błędy są w JSON: { "error": { "code", "message" } }. Częste kody: 400 invalid_request, 401 unauthorized, 403 forbidden, 404 not_found. Pola wyłącznie wewnętrzne (reputacja, wyniki wymiarów, reguły punktacji) nigdy nie pojawiają się w żadnej odpowiedzi.

Jak używać commonspecs