Queek docs

Rules for AI builders

The rules an AI tool (Claude, ChatGPT, Cursor, Lovable, Bolt, v0) must follow when it builds a website, app, server or agent on a Queek store through the Headless API.

These rules are written for an AI that builds on a Queek store, and for the person who pastes the connection's Copy for AI text into it. Follow them in order. They are short on purpose, and each one exists because ignoring it breaks a store or leaks a key.

If you are an AI: the connection brief you were given holds the API address (https://client.usequeek.com/v1), a public key and the allowed websites. Everything else is here and in the quickstart. The complete endpoint list is https://client.usequeek.com/llms.txt and https://client.usequeek.com/openapi.json. Building a server-rendered site? Start from the Next.js starter, and put the site online with Deploy your headless site.

Use only what exists

  1. Call only published endpoints. The list is in the reference. Anything else answers 404 route_not_available. Do not invent a URL, a field or an id.
  2. Identify things by what the API returned. Use the slug or id from a listing. Never guess one.
  3. Send X-Client-Key: <key> and Accept: application/json on every request. The base URL is https://client.usequeek.com/v1.
  4. Branch on error.code, never on message. Quote error.request_id when you report a failure.

Keys

  1. The public key (pk_…) may be in browser and app code. It only works from the websites the merchant allowed.
  2. The secret key (sk_…) never goes in a browser, a mobile app, a public repository, a NEXT_PUBLIC_ / VITE_ / EXPO_PUBLIC_ variable, a screenshot or a chat. Keep it in a server-side environment variable. If you were never given one, do not ask for one: a website or app does not need it. Never read or print .env* (rule 27).
  3. Code that runs on a server has no browser to say which website it came from. A website connection's public key is refused there with 403 origin_required. Ask the merchant for a Server or backend connection and use its secret key on the server, or send an Origin header equal to one of the allowed websites. Mobile apps and AI agents have their own connection types and send no Origin.
  4. Never ask for * or for "any website". It is not accepted. Ask for the exact https:// address the site runs on, or use a Testing on my computer connection while you build.
  5. Build against a dev store first when you can. Browser code uses a Testing on my computer connection and its pk_test_ key; server code uses a Server or backend connection on the dev store and its sk_test_ key. Never put a test key into a production build. Test responses carry the header X-Queek-Mode: test. To launch, a testing connection uses Go live; a Server connection has no Go live, so the merchant creates a new Server connection on the live store and gives the server its sk_live_ key. See Manage a connection and Deploy your headless site.

Prices, stock and content

  1. Prices and stock come from the API, always. Display price exactly as given: it is the final customer price in the store's currency. Never hard-code a price, a product, a stock level, a currency symbol or a delivery fee, and never calculate a discount or a tax.
  2. Re-check the cart before checkout. Call POST /store/cart/validate and fix anything in validation_errors before you send the customer on.
  3. Use the store's own look and words. GET /store/info returns the brand block (logo, colours, fonts, socials), the contact details and the opening hours. Read pages, policies and posts from their endpoints instead of writing your own.
  4. Read custom fields by their schema. Call GET /store/metafield-definitions (add ?owner_type=variant, collection or post for the others) and label a field with its name. Only fields the merchant made public appear. See Custom fields.

The cart and checkout

  1. One random UUID per shopper, sent as X-Cart-Session on every cart call. Store it in the browser (localStorage or a cookie) or in the app. With a signed-in customer token the header is ignored.
  2. Checkout is hosted by Queek. Send the customer to the cart's checkout_url. For example window.location.assign(cart.checkout_url). Take it from the latest cart reply; never build or edit the address yourself.
  3. Do not build a checkout. Do not collect addresses for an order, card numbers or payment details, and do not try to create an order. No order-creation or payment endpoint is published, and none is needed.
  4. Return links. The merchant lists, on the connection, the pages customers return to after paying. To pick one of several, add return_url=<that page> to the cart request. A page the merchant did not list is ignored. Never ask the merchant to disable that check.

After checkout

  1. A redirect is not proof of payment. The return page may be opened by anyone, and the ?queek_order= it carries is only a reference. Show a thank-you message, and nothing more.
  2. Queek runs fulfilment. A storefront never fulfils an order. Only an external fulfilment system the merchant runs listens to orders/paid, never the redirect or orders/create. For a headless site, a webhook is for keeping caches fresh: the merchant creates the endpoint in Settings → Notifications → Webhooks, on products/* topics. Verify the signature of every delivery, answer quickly and dedupe on webhook-id. A site with no server cannot receive webhooks and does not need to: the merchant sees paid orders in the dashboard.
  3. Never promise a delivery or refund from your own code. Order status belongs to Queek.

Customers

  1. Use the published sign-in endpoints (auth/phone/*, auth/email/*, auth/register): one-time code or email and password, whichever the store's design needs. They reply with an access token (valid for one hour) and a refresh token (thirty days).
  2. Send the access token as Authorization: Bearer <token> next to X-Client-Key. Refresh it with POST /auth/token/refresh before it expires, and call POST /auth/logout when the customer signs out. A token belongs to one store.
  3. Keep customer tokens out of URLs, logs and analytics.
  4. An AI agent connection cannot sign customers in or read accounts and orders. It can browse products and build carts only; anything else is 403 agent_access_denied. Give the customer the cart's checkout_url and let them finish there.

When a request fails

  1. Do not work around a refusal. Tell the person what to do.
error.codeWhat it meansWhat to do
403 origin_not_allowedThe website is not on the connection's list. In a browser it may show as a CORS error in the console.Tell the merchant: Open Dashboard → Channels → Headless API → your connection → Problems → Allow your website. Do not change code or headers to get around it.
403 origin_requiredA website key was used by code that sends no website address.Use a Server or backend connection for server code, or a Mobile app connection for an app (rule 7).
403 plan_inactiveA live store needs an active paid website plan.Tell the merchant to upgrade, or to connect a dev store and test there. Do not retry in a loop.
401 invalid_client_keyThe key is wrong, was replaced and turned off, or never existed.Ask for the connection's current key.
401 api_key_mode_mismatchA test key on a live store, or a live key on a dev store.Use the key from the connection on the store you mean.
403 agent_access_deniedAn AI agent connection tried something it may not do.Stay within browsing products and carts.
401 storefront_password_requiredA dev store's storefront is password-protected.Trade the dev store's storefront password (Developers → Dev stores) at POST /auth/storefront/password and send the token as X-Storefront-Token. See Dev stores. A dev-store site is never deployed publicly.
429 too_many_requestsToo many requests.Wait Retry-After seconds, then continue. Cache with ETag.
5xxQueek failed.Retry with backoff, and quote error.request_id.
  1. Be gentle. Do not call the API on every keystroke, load the whole catalogue to render one page, or poll. Send If-None-Match with the ETag you were given: an unchanged resource costs a 304.

Secrets on disk

  1. Never open, read or print a .env* file, and never pipe a secret into a host's command line. Do not cat it, list its values or echo a variable. The merchant pastes secrets into .env.local and into the host's environment settings. Tell them which variables to set and wait. See Deploy your headless site.

Before you tell the merchant it works

  • The first request returns the store's name from GET /store/info, and the connection page reads Connected.
  • A product listing, a product page and a cart render from API data only.
  • Adding a line, validating the cart and pressing checkout lands on Queek's hosted checkout with that cart.
  • No secret key appears anywhere in the code, the build output or the repository.
  • The only websites in play are exact https:// addresses, with no *.
  • Nothing fulfils on a redirect, and the site does not fulfil at all.

To put the site online, continue with Deploy your headless site.

On this page