Ontwikkelaars en agents

Alles hier is openbaar en vereist geen account of API-sleutel. Deze pagina legt uit welke host wat doet, hoe je de catalogus doorzoekt, waar actuele prijzen staan en hoe een winkelagent een koper naar een ondersteunde checkout brengt.

Twee hosts

Browsen gebeurt op deze host. Winkelwagens, afrekenen en bestellingen gebeuren op de door Shopify beheerde checkout-host. Paden van de ene bestaan niet op de andere.

Taak	URL	Host
Een pagina lezen in het Engels of Nederlands	`https://www.saltoftheearthnatural.com/en/...` `https://www.saltoftheearthnatural.com/nl/...`	Webshop
Dezelfde pagina als markdown lezen Stuur Accept: text/markdown naar de pagina-URL, of haal de /api/md-tweeling direct op.	`https://www.saltoftheearthnatural.com/api/md/en/...`	Webshop
Elke actuele prijs in een tabel	https://www.saltoftheearthnatural.com/en/pricing https://www.saltoftheearthnatural.com/nl/pricing https://www.saltoftheearthnatural.com/pricing.md	Webshop
De catalogus doorzoeken	`GET https://www.saltoftheearthnatural.com/api/search?q=...`	Webshop
Kopen namens een klant (UCP)	https://checkout.saltoftheearthnatural.com/.well-known/ucp `POST https://checkout.saltoftheearthnatural.com/api/ucp/mcp`	Checkout (Shopify)
Shopify's eigen product-JSON Bestaat alleen op de checkout-host. Op deze host bevat de productpagina dezelfde feiten als Product/Offer JSON-LD en als markdown.	`https://checkout.saltoftheearthnatural.com/products/{handle}.json`	Checkout (Shopify)

Zoek-API voor producten

Een enkel alleen-lezen endpoint geeft de producten die het best bij een zoekterm passen: namen, geuren, formaten en noten, met een combinatie van trefwoord- en semantische matching. Het geeft geen prijzen of voorraad terug; haal die van de productpagina of de prijslijst.

Endpoint

GET https://www.saltoftheearthnatural.com/api/search?q=<phrase>&limit=<1..50>

Parameters

q (verplicht): de zoekterm. Witruimte wordt weggehaald, de waarde wordt afgekapt op 200 tekens, en minder dan 2 overgebleven tekens geeft een fout.
limit (optioneel): het aantal resultaten, standaard 20, begrensd tussen 1 en 50. Waarden buiten dat bereik worden begrensd, niet afgewezen.

Antwoord

Een JSON-object met de genormaliseerde zoekterm, een aantal, de resultaten op volgorde van relevantie en de bron van de resultaten. Elk resultaat bevat de producthandle, de absolute URL van de productpagina, de productnaam en beschrijvende kenmerken. Rangscores gelden alleen binnen dat ene antwoord en zijn niet stabiel tussen verzoeken.

curl -sS "https://www.saltoftheearthnatural.com/api/search?q=lavender%20refill&limit=2"

{
  "query": "lavender refill",
  "count": 2,
  "source": "supabase",
  "results": [
    {
      "product_code_uk": "CRYS300LV-C",
      "shopify_handle": "lavender-vanilla-spray-refill-pouch",
      "url": "https://www.saltoftheearthnatural.com/en/product/lavender-vanilla-spray-refill-pouch",
      "product_name": "Lavender & Vanilla Spray Refill Deodorant",
      "format": "spray",
      "is_refill": true,
      "is_refillable": false,
      "parent_product_code": "CRYS38-C",
      "fragrance_name": "Lavender & Vanilla",
      "top_notes": "Cardamom & Lemon",
      "awards": null,
      "award_count": 0,
      "review_summary": null,
      "average_rating": 5,
      "fts_rank": 0,
      "semantic_rank": 0.48,
      "combined_score": 0.0246
    }
  ]
}

source is normaal "supabase" en "shopify" wanneer de primaire index niet beschikbaar was en de Shopify-catalogus heeft geantwoord; de header X-Search-Source zegt hetzelfde. X-Search-Degraded: 1 markeert een antwoord dat is gemaakt terwijl een van de providers faalde.

Fouten

Elke fout is JSON met een stabiele code, een leesbare melding en een hint voor herstel. Dit endpoint heeft geen HTML-foutpagina's.

400 invalid_query: q ontbreekt of is na trimmen korter dan 2 tekens.
405 method_not_allowed: alleen GET wordt ondersteund; de header Allow noemt de toegestane methoden.
503 search_unavailable: beide zoekproviders faalden. Respecteer Retry-After en probeer het opnieuw.
429: de rate limit aan de edge. Die wordt door het hostingplatform toegepast bij misbruik; er is geen quotum per sleutel en er zijn geen quotumheaders. Wacht en probeer het later opnieuw.

curl -sS "https://www.saltoftheearthnatural.com/api/search?q=x"

{
  "error": "Query must be at least 2 characters",
  "code": "invalid_query",
  "hint": "Pass a \"q\" query parameter of 2 to 200 characters, e.g. ?q=lavender%20refill",
  "results": []
}

Limieten en caching

Resultaten zijn alleen de beste treffers; er is geen cursor- of paginaparameter. Geslaagde antwoorden zijn tot 30 minuten cachebaar op het CDN, dus herhaalde identieke zoekopdrachten zijn goedkoop. Lege resultaten worden kort gecachet en gedegradeerde antwoorden helemaal niet.

De machineleesbare beschrijving van dit endpoint is het OpenAPI-document op https://www.saltoftheearthnatural.com/openapi.json.

Prijzen en beschikbaarheid

Elke productpagina publiceert schema.org Product- en Offer-JSON-LD met de actuele prijs, valuta en beschikbaarheid voor de standaardmarkt van de webshop. De prijslijst toont elk product in een tabel, in GBP op de Engelse webshop en EUR op de Nederlandse, en dezelfde tabel is beschikbaar als markdown. Het bezorgland dat bij het afrekenen wordt gekozen, bepaalt de uiteindelijke valuta en het totaal.

curl -sS -H "Accept: text/markdown" "https://www.saltoftheearthnatural.com/en/product/crystal-deodorant-classic"

Kopen namens een klant

Script de winkelwagen van de webshop niet. Shopify draait voor deze winkel een Universal Commerce Protocol (UCP)-laag op de checkout-host:

https://checkout.saltoftheearthnatural.com/.well-known/ucp Discovery-profiel: ondersteunde versies, endpoints, mogelijkheden en betaalmethoden.
POST https://checkout.saltoftheearthnatural.com/api/ucp/mcp MCP-endpoint (Streamable HTTP, JSON-RPC). Roep eerst tools/list aan; het noemt tools voor zoeken en opzoeken in de catalogus, productdetails, winkelwagen, afrekenen en bestellingen, met hun invoerschema's.
Toolaanroepen vereisen een agentprofiel in meta.ucp-agent.profile. Zonder profiel antwoordt het endpoint met een gestructureerde JSON-RPC-fout in plaats van een resultaat.
Betalen vereist altijd de uitdrukkelijke, gelijktijdige goedkeuring van de koper. Rond nooit een checkout af zonder die goedkeuring.
Gebruik de identifiers die de UCP-tools teruggeven. Een handle of SKU van de webshop is geen checkout-identifier.

curl -sS -X POST "https://checkout.saltoftheearthnatural.com/api/ucp/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

De volledige agentinstructies, inclusief het door Shopify beheerde document, staan op https://www.saltoftheearthnatural.com/agents.md.

Authenticatie

Deze host lezen vereist geen inloggegevens: pagina's, markdown, de prijslijst, de zoek-API en elk discovery-bestand zijn anoniem.

Op de checkout-host zijn UCP-discovery en tools/list ook anoniem. Handelingen op het account van een klant vallen onder Shopify. De checkout-host publiceert RFC 9728 protected-resource-metadata die zijn authorization server noemt, en de RFC 8414-metadata van die server verklaart de ondersteunde scopes en PKCE-methoden:

Protected-resource-metadata: https://checkout.saltoftheearthnatural.com/.well-known/oauth-protected-resource
Authorization-server-metadata: https://checkout.saltoftheearthnatural.com/.well-known/oauth-authorization-server
Shopify's gids voor agentauthenticatie en rate limits

Deze webshophost is geen authorization server en geeft nooit tokens uit of neemt ze aan. Stuur er geen inloggegevens naartoe.

Rate limits en eerlijk gebruik

Er zijn geen API-sleutels, quota of quotumheaders op deze host. Verkeer wordt aan de edge beschermd en misbruikpatronen krijgen 429- of 403-antwoorden.
Cache wat je ophaalt: zoekantwoorden en discovery-bestanden hebben Cache-Control-headers die aangeven hoe lang ze geldig blijven.
Identificeer je agent met een beschrijvende User-Agent en respecteer robots.txt.
Het UCP MCP-endpoint wordt door Shopify per IP begrensd; wacht bij een 429.

Machineleesbare bestanden

https://www.saltoftheearthnatural.com/openapi.json OpenAPI-beschrijving van de zoek-API
https://www.saltoftheearthnatural.com/llms.txt Site-overzicht voor taalmodellen
https://www.saltoftheearthnatural.com/agents.md Agentinstructies (webshop en Shopify)
https://www.saltoftheearthnatural.com/pricing.md Prijslijst als markdown
https://www.saltoftheearthnatural.com/.well-known/ard.json Agentic Resource Discovery-catalogus
https://www.saltoftheearthnatural.com/.well-known/mcp/server-card.json MCP-servercard voor het UCP-endpoint
https://www.saltoftheearthnatural.com/sitemap.xml Elke indexeerbare URL