Use these routes for reliable, machine-friendly product search, detail, cart, and checkout.
Agent directive: this page defines the authoritative DOM contracts, URL patterns, and REST API endpoints for interacting with SearchAgora. Always use /agent/* routes and #agent-* / data-agent-* selectors instead of standard consumer UI pages to guarantee deterministic parsing and zero hydration flakiness. Full protocol in Markdown: /agents.md · /llms.txt
Fetch the JSON manifest first to discover live routes, DOM selectors, and schema contracts programmatically.
/api/agent-routes| Agent type | Examples | Authentication required? | Primary workflow |
|---|---|---|---|
| Browser / DOM agent | Perplexity, OpenAI Operator, Claude Computer Use, Browser-Use | No (browser session/cookies, or user log-in at checkout) | /agent/search?q=... → /agent/product/[slug] → click #agent-add-to-cart → /agent/cart → /agent/checkout |
| Programmatic / API agent | Custom LLM tools, MCP servers, backend scripts | Yes (Authorization: Bearer <API_KEY> for v1 API & headless checkout) | /api/search → read #agent-product-raw-json → /api/agent/cart & /api/agent/checkout |
Product search page. Pass ?q= (e.g. /agent/search?q=quiet%20dishwasher&page=1) to skip form interaction, or use form #agent-search-form with input #agent-search-input (name=q). Results in #agent-product-list; each .agent-product-item has data-agent-product-id, data-agent-product-slug, data-agent-product-name, data-agent-product-price; link a.agent-product-link to /agent/product/[slug]. Button #agent-fetch-more loads next page.
Single product page. Key fields in #agent-product-meta (data-agent-field, data-agent-value). Full object as JSON in pre#agent-product-raw-json (read .textContent). Add-to-cart form: form#agent-add-to-cart-form.
Items in #agent-cart-items (each row has data-agent-product-id, data-agent-variant-id, data-agent-quantity). Change qty via #agent-cart-quantity-{index} + #agent-cart-update-quantity-{index}; remove with #agent-cart-remove-{index}. Click a#agent-proceed-to-checkout to continue.
Shipping form form#agent-checkout-form; submit with button#agent-submit-order. If your policy requires human confirmation for payment, stop after filling the form and prompt the user.
GET reads the cart. POST sets it: body { items: [{ product, quantity, variantId? }] } with Authorization: Bearer <token>. Proxies to /api/v1/cart. Missing/null variantId defaults to product _id; bad ids return 400.
Create a Stripe PaymentIntent for the API-key user's cart. Returns clientSecret + paymentIntentId. Confirm with Stripe, then pass pm_… / pi_… to checkout. Also on Zues: POST /api/v1/payment-intent.
Optionally send items to set the cart first (POST /api/v1/cart), then place the order with paymentMethodId, paymentIntent, offsetPerc, shippingAddress, and formData.
Fetch order with Authorization: Bearer <token>. Proxies to GET /api/v1/order-tracking/[orderId]. Response: { orderId, status, trackingUrl, estimatedDelivery } or 404. Scoped to the API-key user.
GET /api/agent-routes to get the route manifest (JSON)./agent/search?q={URL_ENCODED_QUERY}&page=1 (or set #agent-search-input and submit the form); read #agent-product-list; use data-agent-product-slug or link data-agent-href to open the product. JSON alternative: GET /api/search?q=...&page=1&count=20 (no auth)./agent/product/[slug]; read #agent-product-meta or parse the .textContent of #agent-product-raw-json for full JSON.#agent-variant-select or [data-agent-variant-id]), set #agent-quantity-input, click #agent-add-to-cart, wait for [data-agent-cart-status="added"], open /agent/cart, click #agent-proceed-to-checkout, fill #agent-checkout-form, click #agent-submit-order./developer-tools/api-keys, send Authorization: Bearer YOUR_API_KEY to https://zues.searchagora.com/api/v1 (see Get an API Key and Authenticate).POST /api/agent/checkout with Bearer token; optional items set the cart first (/api/v1/cart), then the order is placed with Stripe paymentMethodId + paymentIntent (see Step 4).GET /api/agent/orders/[orderId] with Bearer token → { orderId, status, trackingUrl, estimatedDelivery } (own orders only).Use this when integrating Agora into an external application, MCP server, or coding agent via REST (zues.searchagora.com). Agent search and product pages work without a key; the Developer API and headless purchase/order endpoints require one.
Docs: Quickstart · Authentication
Include the bearer token in the Authorization header of all requests to the v1 API:
Authorization: Bearer YOUR_API_KEYBase URL: https://zues.searchagora.com/api/v1
curl -sS \
-H "Authorization: Bearer YOUR_API_KEY" \
"https://zues.searchagora.com/api/v1/search?q=quiet%20dishwasher&count=5"const res = await fetch(
'https://zues.searchagora.com/api/v1/search?q=quiet%20dishwasher&count=5',
{ headers: { Authorization: `Bearer ${process.env.AGORA_API_KEY}` } },
)
const data = await res.json()
// data.Products[] — extract ._id and .slug for detail, cart, and checkout flows
console.log(data.Products?.[0])Replace YOUR_API_KEY / AGORA_API_KEY with the key from step 1. Full API reference: https://docs.searchagora.com/
This document provides the exact DOM contracts and API routes required for an AI agent to programmatically search for products, extract details, add to cart, execute a purchase, and track an order on the Agora platform.
Agents should begin by fetching the manifest to discover available routes and page contracts dynamically.
GET /api/agent-routesapplication/json/agentSkip form interaction by passing the search query directly in the URL:
/agent/search?q={URL_ENCODED_QUERY}&page=1/agent/search?q=quiet%20dishwasher&page=1/agent/search)If already on /agent/search, interact with these guaranteed stable selectors:
| Element Role | Selector | Action / Contract |
|---|---|---|
| Search Form | form#agent-search-form | Submit form to trigger search results. |
| Search Input | input#agent-search-input | Attribute name="q". Set value to the search query string. |
| Submit Button | button#agent-search-submit | Click to execute search. |
| Results Container | #agent-product-list | Parent container holding .agent-product-item cards. |
| Product Card | .agent-product-item | Contains data-agent-* attributes for instant extraction. |
| Product Link | a.agent-product-link | Also matches [data-agent-role="product-detail-link"] or [data-agent-href]. |
| Load More / Next | button#agent-fetch-more | Click to append the next page of results into #agent-product-list. |
Product card data attributes (on .agent-product-item):
data-agent-product-slug: unique URL slug (navigate to /agent/product/[slug]).data-agent-product-id: MongoDB _id of the product (use for cart/checkout payloads).data-agent-product-name: full product title.data-agent-product-price: formatted price string (e.g. $499.00).GET /api/search?q={query}&page={page}&count={count}{ "data": { "Products": [...], "hasMore": true } }Navigate to /agent/product/[slug].
#agent-product-meta)[data-agent-field="name"] — product title[data-agent-field="price"] — current price[data-agent-field="brand"] — brand name[data-agent-field="availability"] — stock status (IN_STOCK / OUT_OF_STOCK)[data-agent-field="store"] — merchant / store namepre#agent-product-raw-json)pre#agent-product-raw-json.textContent (do NOT use .innerHTML, as HTML entity escaping like & will corrupt JSON.parse())._id, slug, name, price, variants (_id, variantId, title, price, available).Important: always use _id (the MongoDB ObjectId string) as the product identifier when adding to cart or checking out. v1 search also returns id with the same value as _id — either works. If variants is empty or omitted, you may omit variantId (or pass null) — the API defaults variantId to the product _id. Malformed ids return 400.
/agent/product/[slug]:select#agent-variant-select (set value to the target variantId) or click [data-agent-variant-id="<variant_id>"].input#agent-quantity-input (default 1).button#agent-add-to-cart (inside form#agent-add-to-cart-form).[data-agent-cart-status="added"] (other values: idle, adding, error), then follow a#agent-view-cart to /agent/cart./agent/cart and /agent/checkout:#agent-cart-items (each row has data-agent-product-id, data-agent-variant-id, data-agent-quantity).input#agent-cart-quantity-{index} then button#agent-cart-update-quantity-{index}.button#agent-cart-remove-{index} (cart is account-scoped).a#agent-proceed-to-checkout.form#agent-checkout-form: #agent-first-name (firstName), #agent-last-name (lastName), #agent-email (email), #agent-address-line1 (addressFirst), #agent-city (city), #agent-state (state), #agent-zip (zipCode), select#agent-country (country, ISO 2-letter code e.g. US).button#agent-submit-order (label: "Place order"; progress in [data-agent-checkout-status]: idle, invalid, awaiting-payment). Checkout shows #agent-checkout-items and #agent-checkout-total. If policy requires human payment confirmation, stop after submit and let the user finish on /checkout.(Requires Bearer authentication — see Get an API Key and Authenticate. Premium required — pricing.)
Optionally set the cart on its own: POST /api/agent/cart with body { "items": [{ "product": "<_id>", "quantity": 1, "variantId": "<variantId_if_applicable>" }] }. Proxies to POST /api/v1/cart. Response: { "status": "success", "items": [...] }. Omit/null variantId defaults to product _id. Unknown products → 404; bad id strings → 400.
Create a PaymentIntent: POST /api/agent/payment-intent (Bearer) → { clientSecret, paymentIntentId, stripeCustomerId, publishableKey }. Confirm with Stripe.js using publishableKey + clientSecret, then call checkout with paymentMethodId + paymentIntent. Staging: POST /api/v1/payment-intent.
POST /api/agent/checkout accepts an items array to populate the cart, then submit the order in one call.
POST /api/agent/checkoutContent-Type: application/json, Authorization: Bearer <YOUR_API_KEY>{
"items": [
{ "product": "<_id_from_search_or_agent_product_raw_json>", "quantity": 1, "variantId": "<variantId_if_applicable>" }
],
"paymentMethodId": "pm_...",
"paymentIntent": "pi_...",
"offsetPerc": 0,
"shippingAddress": {
"firstName": "Jane", "lastName": "Doe", "addressFirst": "123 Market St",
"city": "San Francisco", "state": "CA", "zipCode": "94105", "country": "US"
},
"formData": {
"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com",
"addressFirst": "123 Market St", "city": "San Francisco", "state": "CA",
"zipCode": "94105", "country": "US"
}
}paymentMethodId / paymentIntent: call POST /api/agent/payment-intent to create a PaymentIntent on Agora's Stripe account, then confirm it (Stripe.js, Elements, or the Stripe API) until status is succeeded. Pass the resulting pm_… and pi_… ids into checkout.offsetPerc: optional percentage (0–100) of the merchandise total to cover with Agora shopping credits. Use 0 (default) to charge the full amount to the payment method.formData vs shippingAddress: for headless/guest checkout, formData wins for name, email, and address lines (it is what the order API reads). Send the same address fields in both if you include shippingAddress; do not rely on shippingAddress alone.Response (200 OK): { "status": "success", "order": { ... } } — order contains orderId / _id and initial status.
Query real-time fulfillment and tracking details using the orderId returned at checkout.
GET /api/agent/orders/[orderId]Authorization: Bearer <YOUR_API_KEY>{ orderId, status, trackingUrl, estimatedDelivery } or 404. Only the API-key owner’s orders are readable.{
"orderId": "12345",
"status": "SHIPPED",
"trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=...",
"estimatedDelivery": "2026-10-24"
}