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
- 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. - Identify things by what the API returned. Use the
slugoridfrom a listing. Never guess one. - Send
X-Client-Key: <key>andAccept: application/jsonon every request. The base URL ishttps://client.usequeek.com/v1. - Branch on
error.code, never onmessage. Quoteerror.request_idwhen you report a failure.
Keys
- The public key (
pk_…) may be in browser and app code. It only works from the websites the merchant allowed. - The secret key (
sk_…) never goes in a browser, a mobile app, a public repository, aNEXT_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). - 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 anOriginheader equal to one of the allowed websites. Mobile apps and AI agents have their own connection types and send noOrigin. - Never ask for
*or for "any website". It is not accepted. Ask for the exacthttps://address the site runs on, or use a Testing on my computer connection while you build. - 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 itssk_test_key. Never put a test key into a production build. Test responses carry the headerX-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 itssk_live_key. See Manage a connection and Deploy your headless site.
Prices, stock and content
- Prices and stock come from the API, always. Display
priceexactly as given: it is the final customer price in the store'scurrency. 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. - Re-check the cart before checkout. Call
POST /store/cart/validateand fix anything invalidation_errorsbefore you send the customer on. - Use the store's own look and words.
GET /store/inforeturns thebrandblock (logo, colours, fonts, socials), the contact details and the opening hours. Read pages, policies and posts from their endpoints instead of writing your own. - Read custom fields by their schema. Call
GET /store/metafield-definitions(add?owner_type=variant,collectionorpostfor the others) and label a field with itsname. Only fields the merchant made public appear. See Custom fields.
The cart and checkout
- One random UUID per shopper, sent as
X-Cart-Sessionon every cart call. Store it in the browser (localStorageor a cookie) or in the app. With a signed-in customer token the header is ignored. - Checkout is hosted by Queek. Send the customer to the cart's
checkout_url. For examplewindow.location.assign(cart.checkout_url). Take it from the latest cart reply; never build or edit the address yourself. - 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.
- 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
- 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. - Queek runs fulfilment. A storefront never fulfils an order. Only an external fulfilment
system the merchant runs listens to
orders/paid, never the redirect ororders/create. For a headless site, a webhook is for keeping caches fresh: the merchant creates the endpoint in Settings → Notifications → Webhooks, onproducts/*topics. Verify the signature of every delivery, answer quickly and dedupe onwebhook-id. A site with no server cannot receive webhooks and does not need to: the merchant sees paid orders in the dashboard. - Never promise a delivery or refund from your own code. Order status belongs to Queek.
Customers
- 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). - Send the access token as
Authorization: Bearer <token>next toX-Client-Key. Refresh it withPOST /auth/token/refreshbefore it expires, and callPOST /auth/logoutwhen the customer signs out. A token belongs to one store. - Keep customer tokens out of URLs, logs and analytics.
- 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'scheckout_urland let them finish there.
When a request fails
- Do not work around a refusal. Tell the person what to do.
error.code | What it means | What to do |
|---|---|---|
403 origin_not_allowed | The 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_required | A 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_inactive | A 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_key | The key is wrong, was replaced and turned off, or never existed. | Ask for the connection's current key. |
401 api_key_mode_mismatch | A 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_denied | An AI agent connection tried something it may not do. | Stay within browsing products and carts. |
401 storefront_password_required | A 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_requests | Too many requests. | Wait Retry-After seconds, then continue. Cache with ETag. |
5xx | Queek failed. | Retry with backoff, and quote error.request_id. |
- Be gentle. Do not call the API on every keystroke, load the whole catalogue to render one
page, or poll. Send
If-None-Matchwith theETagyou were given: an unchanged resource costs a304.
Secrets on disk
- Never open, read or print a
.env*file, and never pipe a secret into a host's command line. Do notcatit, list its values or echo a variable. The merchant pastes secrets into.env.localand 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.
Related
Deploy your headless site
Pick Server or Website, set the keys on Vercel, Netlify or Cloudflare, and go live.
Next.js starter
A server-rendered storefront on the Headless API.
Headless API quickstart
Connect, read the catalogue, build a cart and hand it to checkout.
Manage a connection
Keys, allowed websites, return links, status, going live.
Payments
What happens between checkout_url and orders/paid.
Webhooks
Order events, signatures and retries.
Headless API quickstart
Connect a website, mobile app, server or AI agent to a Queek store. Get keys from Channels → Headless API, read the catalogue, build a cart and hand it to Queek checkout. Formerly called the Storefront API.
Manage a connection
Replace or turn off a Headless API key, set allowed websites and after-checkout return links, read the Is it working status and plain-English errors, go live from a dev store, or disconnect.