Build an integration with an AI agent

Copy the prompt below into your coding agent. Give the agent your store’s configuration when it asks. The reference sections apply to any merchant. Use the collections-only prompt for a migration limited to category and collection pages.

Agent prompt

Integrate the Depict Platform API into our stack for search, listings, recommendations and tracking.
Follow https://docs.depict.ai/api-guide/introduction and https://docs.depict.ai/api-guide/search
Follow https://docs.depict.ai/api-guide/listings, https://docs.depict.ai/api-guide/recommendations/api and https://docs.depict.ai/api-guide/tracking/introduction
Use the endpoint reference: https://docs.depict.ai/api-reference/headless/overview#api-overview
Read the machine contract: GET https://api.depict.ai/openapi.json
Treat actual serving responses as the runtime authority. Verify event acceptance and attribution in the portal's Tracking status tab.
Ask me for our merchant id, our markets and locales, recommendation surfaces, and where catalog and tracking data live.

Runtime authority

The published machine contract is GET https://api.depict.ai/openapi.json. It describes request and response schemas. It does not define every merchant-specific display field or establish tracking attribution. Use actual serving responses for the requested merchant, market and locale. Check HTTP status and response error fields. A successful tracking response confirms batch validation. Confirm attribution in the portal’s Tracking status tab. Read the integration guides with the generated endpoint reference.

Integration scope and SSR

Build your storefront with direct Platform API calls. Render the first search and listing results with server-side rendering (SSR). Preserve API ranking, filters, pagination, navigation, prices and availability. For a migration, compare these results with the existing integration. Use your merchant configuration and its valid market/locale pairs. Use /v3 serving endpoints at https://api.depict.ai. Keep DPC for browser tracking. Confirm how your storefront supplies a common session during the first SSR request and subsequent browser interactions.

Endpoints and response fields

All serving routes in this table require merchant, market and locale. GET routes use query parameters. POST routes use JSON bodies. Use the same session_id in supported serving requests and tracking.

Method and exact path	Other request fields	Fields to use
POST `/v3/search/results`	Optional `query`, `filters`, `sort`, pagination	`displays`, `n_hits`, `filters`, `sorts`, `search_request_id`, `cursor` or `page`, `content_search_links`
GET `/v3/search/suggestions`	Optional `query`, `limit` 1–10, default 3	`suggestions_request_id`, `suggestions`; query suggestions use `type`, `query`, `suggestions_result_id`; listing suggestions use `listing_id`, `title`, `slug`, `ancestors`, `suggestions_result_id`
GET `/v3/listings/{listing_id}` or `/v3/listings/external_id/{external_id}`	Required path ID; optional `session_id`	`listing_id`, `external_id`, `listing_type`, `title`, optional `slug` and `page_url`, `image_urls`, navigation flags, `ancestors`, `children`, `siblings`, `content_blocks`
POST `/v3/listings/{listing_id}/products` or `/v3/listings/external_id/{external_id}/products`	Required path ID; optional `filters`, `sort`, pagination	`displays`, `n_hits`, `filters`, `sorts`, `product_listing_request_id`, `cursor` or `page`; metadata comes from GET
POST `/v3/recommend/products`	Required `type`; optional `product_ids`, `limit` 1–128	`displays`, `error`; optional `variant`, `experiment_id`

Discover IDs with GET /v3/markets?merchant={merchant} and GET /v3/locales?merchant={merchant}. Their response fields are markets and locales. These routes require only merchant. The lists do not establish all valid market/locale combinations. GET /v3/listings requires merchant, market and locale. It returns the navigation tree. Use the recommendation type configured for each surface and market. Common names include after_basket and checkout. Confirm their availability with Depict. Preserve each surface’s existing product context during a migration. Empty product_ids selects general recommendations. One ID selects product recommendations. Multiple IDs select recommendations for that set. Use the API’s product_id values for the product context. Choose one pagination mode. Cursor mode uses limit from 1 to 250 and optional cursor. Page mode uses page from 1 and required hits_per_page from 1 to 200. Never mix the modes. Start without a cursor. Send each returned cursor unchanged. Stop when no cursor remains. Reset pagination when the query, listing, filters, sort, market or locale changes. n_hits can be approximate. Build facets from returned filters and sorting controls from sorts. Send selected field, op and data. Read meta.type, meta.values, meta.counts, meta.names, range bounds and optional meta.currency. Preserve each filter’s returned operator. Send a returned sort’s field and order. For quicklinks, select the unfiltered children array when it contains entries. Otherwise, select siblings. Then filter by show_in_quicklinks. If your design includes parent quicklinks, read them independently from raw ancestors. Exclude the current ID from the parent group. Remove duplicate IDs. Preserve the returned order. Build breadcrumbs from ancestors with show_in_breadcrumbs: true, root first. Use a returned page_url when available. Otherwise, use your route function with the full slug chain. Child paths include the current listing’s slug. Hidden navigation labels must not remove route segments. Preserve content_blocks placement.

Tracking

Initialize new DPC(merchant, { market }) once in the browser. Call dpc.setSessionId(session_id) with the serving session. Update DPC on market changes. Tag each card with its outer display result ID. Search uses data-search-result-id. Listings use data-product-listing-result-id. Recommendations use data-recommendation-id. DPC records card clicks. Request IDs cannot replace card result IDs. Implement card visibility events separately. POST /create-events accepts a JSON array. Each impression uses tenant, market, session_id, type: "element_visible", selected product_id and the corresponding result ID field. Set tenant to your merchant identifier. Send impressions when cards become visible. Avoid duplicate senders. Result IDs expire after 10 minutes. Confirm attribution in Tracking status. HTTP 200 alone is insufficient. On every PDP visit, call dpc.setProductId(product_id). After each successful cart addition, call dpc.sendAddToCartEvent({ product_id }) with the added variant. Send all purchases once through dpc.sendPurchaseEvent. Supply a stable transaction_id, items and the actual ISO currency. Each item needs item_id, final per-unit price and integer quantity of at least 1. Purchase item_id uses the ingested transaction product ID. Confirm that mapping for your catalog. Missing events reduce recommendation quality and ranking feedback.

Rendering and operation

Confirm your merchant’s display mapping before assigning product types. If it uses variant_displays and variant_index, select display.variant_displays[display.variant_index]. Preserve the outer result ID. Your cards need a product identity, title, image, price, availability state and product URL. Common variant fields include product_id, title, image_urls or image_url, sale_price and original_price. Use in_stock if your mapping supplies it. Create missing product URLs with your route mapping and display transformer. Confirm any URI field before using it. Disable purchase controls for unavailable variants. Preserve API order. Use an image placeholder for missing images. Prices already reflect the requested market and locale. The serving API has no currency request parameter. Retain your storefront’s configured market currency and price formatter. Cache listing metadata and the tree by merchant, market, locale and ID for at most 10 seconds. Suggestions have a one-hour cache header. Keep product responses and SSR HTML containing result IDs out of shared caches. Obtain fresh result IDs from new serving responses. Choose a serving timeout within your storefront’s page budget. A starting budget is 1,500 ms per request. This is a project choice, not an API guarantee. Handle failed HTTP status, malformed JSON and recommendation error with an empty component. Keep the page usable. Log status and any Error ID. Preserve your canonical URLs and SEO metadata.

Acceptance checks

Use your catalog, routes, configured surfaces and market/locale pairs. For a migration, compare the existing integration with the API implementation under the same session, query, filters, sort and page size. For a new integration, compare each rendered view with its API response.

Test representative product queries, a query with no matches and selected filters.
Test a listing with children, a listing with siblings and a root listing.
Verify flagged parent links when the current listing is absent from child quicklinks.
Traverse pagination through its last page. Check order, termination and duplicate cards.
Compare each recommendation surface with the same product context.
Repeat the checks for each configured market/locale pair.
Check initial SSR HTML, hydration, navigation, empty states and timeouts.
Verify card, PDP, add-to-cart and purchase events with the correct identities.

Equal means the same ordered products, variants, prices, availability, images, filter selections/counts and URL targets. Generated tracking IDs can differ. For read-only search and listing comparisons, use track: false. Omit session_id for anonymous checks. Verify actual tracking separately with attributable user journeys.

Sources and open questions

Use these public guides with the API overview and GET https://api.depict.ai/openapi.json:

API introduction: request conventions, discovery routes, markets, locales and currency.
Search: results, suggestions, filters, sorting, pagination, product data and errors.
Listings: metadata, products, cache headers, hierarchy and navigation rules.
Recommendations: configured types, product context and response fields.
DPC setup: browser initialization.
Card tracking: click attributes and visibility events.
Tracking IDs: result IDs, product IDs, transaction IDs and event validation.
PDP tracking, add-to-cart tracking and purchase tracking: event requirements.
DPC reference: market and shared session configuration.
Display transformers: product URLs and variant fields.
Published OpenAPI contract: machine-readable request and response schemas.

Ask Depict to confirm recommendation types and product context per market, transaction IDs, initial SSR session handling, display/stock mapping and missing slug handling. Confirm rate limits, retry guidance, cache invalidation and migration dates. Obtain answers before enabling the affected features.

​Agent prompt

​Runtime authority

​Integration scope and SSR

​Endpoints and response fields

​Tracking

​Rendering and operation

​Acceptance checks

​Sources and open questions