Build collection pages with an AI agent

Use this prompt when you want to replace collection and category grids with Platform API calls. Copy it into your coding agent. Use the full integration prompt for a migration that also includes search and recommendations.

Agent prompt

Integrate Depict collection and category listings into our storefront with direct Platform API calls.
Follow https://docs.depict.ai/api-guide/listings
Use https://docs.depict.ai/api-guide/search#pagination and https://docs.depict.ai/api-guide/search#filters for request controls.
Follow https://docs.depict.ai/api-guide/tracking/product-cards and https://docs.depict.ai/api-guide/tracking/ids
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 card event acceptance and attribution in Tracking status.
Ask me for our merchant id, our markets and locales, listing IDs, and where product routes and tracking data live.

Runtime authority

Read the published machine contract at GET https://api.depict.ai/openapi.json. Use actual serving responses for your merchant, market and locale. Confirm card event acceptance and attribution in the portal’s Tracking status tab. HTTP 200 alone does not prove attribution. Product fields depend on the merchant’s display mapping.

Scope and server rendering

Replace only the category and collection page integration. Keep the store’s existing search, recommendation and other tracking integrations. Render products, navigation and metadata in the first server response. Hydrate that response without a second first-page request. Fetch metadata and products independently when their listing ID is already known. Use the same session identity in serving requests and browser events. Confirm how the store supplies that identity during the first SSR request. If your current grid renders after browser mounting, move its first render to the server. Reuse your storefront’s route function, product card design and currency formatter.

Endpoint contract

Use https://api.depict.ai. GET requests carry query parameters; POST requests carry JSON bodies. Required serving fields are merchant, market and locale. Send session_id for attributable product requests.

Method and path	Other request inputs	Response fields
GET `/v3/listings/{listing_id}`	Required UUID path ID; optional `session_id`	Listing metadata below
GET `/v3/listings/external_id/{external_id}`	Required merchant listing ID; optional `session_id`	Same metadata shape
POST `/v3/listings/{listing_id}/products`	Required path ID; optional `filters`, `sort`, pagination	`displays`, `n_hits`, `filters`, `sorts`, `product_listing_request_id`, `cursor` or `page`
POST `/v3/listings/external_id/{external_id}/products`	Required merchant listing ID; same body	Same product response shape

Listing product requests have no query field. Product responses do not contain listing metadata. Fetch that metadata with the GET route. Use the existing CMS mapping to obtain the listing ID or external ID. For discovery, GET /v3/markets?merchant={merchant} returns markets. GET /v3/locales?merchant={merchant} returns locales. These routes require only merchant. Separate lists do not establish every valid market/locale pair.

Pagination, filters and sorting

Choose one pagination mode:

Cursor mode: send limit from 1 to 250. Omit cursor initially. Send each returned cursor unchanged. Stop when no cursor remains.
Page mode: send page from 1 and hits_per_page from 1 to 200. hits_per_page is required with page.

Do not mix the modes. Reset pagination when the listing, filters, sort, market or locale changes. Keep the current storefront’s page size and navigation behavior. Do not treat approximate n_hits as proof of completeness. Build controls from returned filters and sorts. Send the chosen filter’s field, op and selected data. Read meta.type, meta.values, meta.counts, meta.names, range min/max, and optional meta.currency. Use the documented selection format for each filter type. Keep its returned operator. Send a returned sort’s field and order.

Metadata, breadcrumbs and quicklinks

Use listing_id, optional external_id, listing_type, title, optional slug and page_url, image_urls, show_in_breadcrumbs, show_in_quicklinks, ancestors, children, siblings and content_blocks. Use content_blocks for the API’s merchandising cards. Preserve any existing CMS content placement required by the storefront. The response supplies raw hierarchy arrays. It does not supply computed quick_links or breadcrumbs arrays. To preserve SDK quicklink selection:

Select the unfiltered children array when it contains entries.
Otherwise, select siblings.
Keep entries with show_in_quicklinks: true.
Keep the returned order.

Build parent quicklinks independently from raw ancestors. Keep flagged parents in their returned order. Exclude the current listing_id from the parent group. Remove duplicate IDs. The current category need not occur in child quicklinks. Sibling quicklinks can include the current category. Build breadcrumbs from ordered ancestors with show_in_breadcrumbs: true. Display the current category according to the existing page design. Use a supplied page_url when available. Otherwise, use the storefront route function with the complete ancestor slug chain. Add the current slug for a child path. Use the current ancestors for a sibling path. Hidden navigation labels must not remove URL segments. Resolve missing slugs through the CMS. A listing with children can omit the current category from its quicklink selection. Read parent links from metadata instead of requiring the current category to occur in that selection.

Product card data

Confirm your merchant’s display mapping before assigning product types. If your mapping uses variant_displays and variant_index, select display.variant_displays[display.variant_index]. Keep product_listing_result_id on the outer display. Common selected-variant fields include product_id, title, image_urls, sale_price and original_price. Use in_stock if your mapping supplies it. Your cards need an availability state and a product URL. Confirm the complete mapping for each market. Use a returned product page_url when available. Create missing URLs with your storefront’s route function and its confirmed display fields. Support a documented single image_url mapping when applicable. Provide a placeholder for missing images. Disable purchase controls for unavailable variants. Keep API product order and returned prices. Retain the store’s configured market currency and price formatter. No serving currency request parameter exists.

Card clicks and impressions

Reuse the browser’s DPC instance. Set the same serving session through dpc.setSessionId(session_id). Update DPC when the active market changes. Add data-product-listing-result-id to each card, using its exact outer product_listing_result_id. DPC records card clicks from this attribute. The response’s product_listing_request_id cannot replace a card result ID. Add visibility tracking separately. A custom sender posts a JSON array to POST https://api.depict.ai/create-events. Each card impression carries tenant, market, session_id, type: "element_visible", product_listing_result_id and the selected product_id. This event endpoint uses tenant; serving requests use merchant. At least one identity field is required. Send visibility events from the browser. Server rendering alone is not an impression. Check existing senders to prevent duplicate events. A custom click sender can use the same endpoint with type: "click" and the card result ID. Use one click sender. Result IDs expire after 10 minutes. Confirm event arrival and product matching in Tracking status.

Caching, timeouts and errors

Cache listing metadata by merchant, market, locale and ID for at most 10 seconds, as its cache header permits. Chosen project policy: keep product responses and SSR HTML with result IDs out of shared caches. Obtain fresh result IDs from new product responses before their attribution lifetime expires. Choose a request deadline within the storefront’s SSR budget. A starting project budget is 1,500 ms per serving request. This is not an API guarantee. Check HTTP status before reading display fields. Handle invalid requests, missing listings, malformed JSON and temporary failures with an empty component. Keep the rest of the page usable. Log status and any Error ID. Preserve the existing canonical URL and SEO metadata.

Acceptance checks

For a migration, compare the existing integration and API with the same listing, session, market, locale, filters, sort and page size. For a new integration, compare the rendered view with its API response. For anonymous API comparisons, omit session_id and use track: false. Do not send comparison impressions. Verify actual tracking separately with attributable user journeys.

Compare a listing with children. Verify its flagged parents and child links.
Compare a leaf listing. Verify sibling links and the current listing’s active state.
Compare a root listing. Check navigation without ancestors and apply returned filters and sorts.
Traverse pagination through its last page. Check order, termination, omissions and duplicate cards.
Repeat for every configured market/locale pair. Check titles, URLs, prices, currency and availability.
Check initial SSR HTML, hydration, client navigation, empty results and timeout handling.
Verify card clicks and visibility events with the returned result IDs and the common session.

Equal means the same ordered products, selected variants, prices, stock state, images, filter selections/counts and URL targets. Newly generated IDs can differ. Parent links must remain available when child quicklinks omit the current listing.

Sources and open questions

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

Listings: endpoints, metadata, cache headers, hierarchy and navigation rules.
Search controls: pagination, filters, sorting and common card fields.
API introduction: discovery routes, market/locale combinations and currency behavior.
Card tracking: click attributes and visibility events.
Tracking IDs: identity, result ID lifetime and validation.
DPC reference: market and shared session configuration.
Display transformers: product URLs and variant fields.
Published OpenAPI contract: machine-readable request and response schemas.

Confirm listing IDs and locale pairs, the display mapping, stock and pre-order behavior, first SSR session handling, missing slugs, caching and retry policy. Confirm rate limits and API migration dates with Depict. The timeout and SSR cache policies above are implementation choices.

​Agent prompt

​Runtime authority

​Scope and server rendering

​Endpoint contract

​Pagination, filters and sorting

​Metadata, breadcrumbs and quicklinks

​Product card data

​Card clicks and impressions

​Caching, timeouts and errors

​Acceptance checks

​Sources and open questions