Developer documentation

Discovery

• robots.txt provides crawler guidance and the sitemap location.
• sitemap.xml is the sitemap index for the shop’s publicly released languages.
• /.well-known/ai-catalog.json lists machine-readable resources and is advertised through a Link header with rel="ai-catalog".
• /.well-known/ard.json is an alias serving the same catalog, with an additional rel="ard" Link value for the ARD v0.91 draft.
• llms.txt gives a short overview of the range, services and data access options.
• Product and category pages include JSON-LD with structured product information, prices and availability.

Product API

The public API base URL is https://api.saneq.ch. Read access is anonymous and requires no API key. These GET endpoints return JSON.

• GET /shop/products: search, filter and paginate products.
• GET /shop/products/{titleSlug}[/{variantSlug}]: retrieve a product or a specific variant. The part in square brackets is optional.
• GET /shop/products/{titleSlug}/reviews: retrieve a product’s reviews.
• GET /shop/categories/by-path/{pfad}: look up a category by its path.
• GET /categories/tree: retrieve the category tree.
• GET /shop/brands: list available brands.
• GET /shop/store-policy: retrieve machine-readable return and shipping information.

Parameters and example

Product lists accept q for search text, categorySlug for a category, brand or brandId for a brand, and priceMin and priceMax for price filtering. Use inStock to filter by stock availability, attr for attribute filters and range for value ranges. page selects a page, pageSize sets its size up to 100 results, and sort selects the sort order.

Choose a language with lang=de|fr|it|en; requests without this parameter use German. Product and category requests should use slugs from the requested language.

Example: https://api.saneq.ch/shop/products?q=tape&inStock=true&page=1&pageSize=20&lang=en

Understanding response fields

Prices are gross amounts in CHF, including tax. Fields ending in Minor contain minor units, or Swiss centimes: 1290 means CHF 12.90. descriptionPlain is the description without HTML. Entries in specs include rawValue and unitCode for machine-readable attribute values and units. availability describes availability. Product detail responses carry a public Cache-Control header.

MCP server

Connect a client that supports remote MCP servers, such as Claude Desktop or a compatible ChatGPT connector, to https://api.saneq.ch/mcp. Use Streamable HTTP transport with no authentication: the catalog requires neither an account login nor an API key.

• search_products searches the catalog by text, category or brand and returns at most 20 results per page, with page numbering starting at 0.
• get_product retrieves details, specifications, the price including VAT, availability and the product URL using a product title slug and an optional variant slug.
• check_availability checks availability, prices including VAT and delivery times for up to 50 product IDs and reports missing IDs separately.
• list_categories lists public categories with their paths and product counts in the requested language.
• get_store_policy returns the current return, shipping and delivery policies.

The JSON resources saneq://store-policy and saneq://categories provide store policies and categories. The categories resource is in German; use list_categories for other languages. The recommend_product prompt helps recommend products based on a need, an optional budget in CHF and a language.

The separate cart endpoint https://api.saneq.ch/mcp/cart also uses Streamable HTTP. Authenticate with Authorization: Bearer sk_… and an API key with the cart:write scope. It offers create_cart(items[{productId, quantity}], locale?, buyerEmail?), get_cart(cartId) and update_cart(cartId, items), plus the five read tools from /mcp. There is no checkout tool: continue_url is the only way to proceed to checkout, which the customer completes in the shop. Quote prices and availability only from tool results.

API keys

An API key with cart:write is required for the agent cart API and the separate MCP cart endpoint. The public product API, MCP catalog, cart deep links and handoff API can be used anonymously without an API key.

Request a key by emailing [email protected] with a description of your integration, the scopes you need and your expected request volume. The saneq team creates and manages keys in the admin interface.

Send the key in either HTTP header: Authorization: Bearer sk_… or X-Api-Key: sk_…. Keep it in your server-side integration and do not include it in public links.

• catalog:read identifies catalog read access with a key; anonymous catalog access remains available without a key.
• cart:write allows you to create, read, update and cancel the API client’s own agent carts; this scope does not authorize completing a purchase.

Catalog requests and the agent cart API use a separately configured per-minute limit for each API client and its key, with a default of 600 requests per minute. The limit agreed for your key applies. Rotating the key does not reset this quota.

Ask the saneq team to rotate or revoke keys in the admin interface as needed. Rotation replaces the previous key with a new one; update your integration accordingly. The full key is returned only once, when it is created or rotated.

Prepare a cart for customers

These interfaces prepare a cart. The customer reviews the items, adds them to their cart in the shop and completes the purchase themselves. No order or payment is initiated without this step. The items, tokens and amounts below are illustrative examples; use IDs and SKUs from the current catalog.

Deep link: use the format /warenkorb?add=SKU:qty,SKU:qty with at most 20 lines and integer quantities from 1 to 99. No API key is needed. Example in English:

https://www.saneq.ch/en/cart?add=ART-123:2,ART-456:1

The localized paths are /fr/panier?add=SKU:qty,…, /it/carrello?add=SKU:qty,… and /en/cart?add=SKU:qty,…. The link lets the customer review the proposed items before adding them to their cart.

Handoff API: POST /shop/cart/handoff anonymously creates a handoff link from items and locale (de, fr, it or en). Each line contains either a numeric productId or a sku, plus quantity. Requests accept 1–50 lines and quantities from 1 to 999.

Example request:

POST https://api.saneq.ch/shop/cart/handoff Content-Type: application/json { "items": [ { "sku": "ART-123", "quantity": 2 } ], "locale": "en" }

Example response; skipped identifies omitted lines:

HTTP/1.1 201 Created { "token": "bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA", "continueUrl": "https://www.saneq.ch/en/cart/resume/bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA", "expiresAtUtc": "2026-10-14T10:00:00Z", "skipped": [] }

Give the returned continueUrl to the customer. GET /shop/cart/handoff/{token} shows the items with current prices and availability. After confirmation, the shop adds them using POST /shop/cart/handoff/{token}/redeem and the destination cart’s X-Cart-Key. Redeeming the same token again into that cart does not add the quantities twice; unknown or expired tokens return 404.

Agent cart API based on ACP-Cart: the base URL is https://api.saneq.ch/agent/carts. All calls require an API key with cart:write and operate on that API client’s own carts.

• POST /agent/carts creates a cart and returns 201.
• GET /agent/carts/{id} reads the cart with current prices and availability.
• PUT /agent/carts/{id} replaces all lines with the supplied list.
• POST /agent/carts/{id}/cancel cancels the agent cart; handoff links already issued remain valid until they expire.

Send API-Version: 2026-04-17 with all four operations. Create and Cancel also require an Idempotency-Key containing 1–128 printable ASCII characters: use a new value for each new operation and reuse it when retrying the same request. PUT does not require this header. line_items contains 1–50 lines with an id in the format v{productId} and a quantity from 1 to 999.

Create example; replace the example key with your own:

POST https://api.saneq.ch/agent/carts Authorization: Bearer sk_… API-Version: 2026-04-17 Idempotency-Key: cart-demo-001 Content-Type: application/json { "line_items": [ { "id": "v12345", "quantity": 2 } ], "locale": "en" }

Excerpt from an example response:

HTTP/1.1 201 Created API-Version: 2026-04-17 { "id": "f268c6ea-89af-4183-a426-b75bdcaa32c5", "line_items": [ { "id": "line_12345", "item": { "id": "v12345", "name": "Example product", "unit_amount": 1290 }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 2580 } ] } ], "currency": "chf", "totals": [ { "type": "subtotal", "amount": 2580 }, { "type": "shipping", "amount": 790 }, { "type": "total", "amount": 3370 } ], "continue_url": "https://www.saneq.ch/en/cart/resume/bW9ja19oYW5kb2ZmX3Rva2VuXzMyX2J5dGVzXzAwMDA" }

unit_amount and totals[].amount are integers in minor units: with currency: "chf", 1290 means CHF 12.90. Product prices include VAT; shipping amounts are estimates. Check the information in messages and give the current continue_url to the customer. This API does not offer checkout.

Store policy

GET /shop/store-policy provides machine-readable return and shipping information, including the return window, return method, costs and delivery times. Use this data in your integration and account for any product-specific return exclusions.

Fair use

• Anonymous catalog requests are subject to the catalog-read limit of 300 requests per minute per IP address. Avoid unnecessary retries and traffic bursts; requests with an API key use the individual per-minute limit.
• If the limit is exceeded, you receive HTTP 429. Wait for the number of seconds specified in the Retry-After header before trying again.
• Respect Cache-Control headers and reuse responses during their stated lifetime. Product details use, for example, public, max-age=300, stale-while-revalidate=3600. Responses with private, no-store, including cart handoffs, must not be cached.
• Credit “saneq.ch” as the source when using the data.
• Prices and availability can change. Prices shown outside the shop are not guaranteed; the information in the shop takes precedence.
• For integration questions, contact [email protected].

For retries during customer checkout, POST /shop/checkout/orders supports the Idempotency-Key header containing 1–128 printable ASCII characters. Use the same key for the same cart and request body, for example after a connection failure.

• A replay returns the stored response with Idempotent-Replayed: true.
• Reusing the key for a different cart or request returns HTTP 422 with checkout.idempotency-mismatch.
• If the first attempt is still being processed, the response is HTTP 409 with checkout.idempotency-in-progress and Retry-After: 2; retry the identical request after waiting.

Checkout idempotency prevents duplicate order attempts; it does not authorize agents to complete a purchase without the customer.