> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build collection pages with an AI agent

> A short agent prompt and API reference instructions for category and collection pages.

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](/api-reference/headless/build-with-ai-agent) for a
migration that also includes search and recommendations.

## Agent prompt

```text theme={null}
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:

1. Select the unfiltered `children` array when it contains entries.
2. Otherwise, select `siblings`.
3. Keep entries with `show_in_quicklinks: true`.
4. 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](https://docs.depict.ai/api-reference/headless/overview#api-overview)
and `GET https://api.depict.ai/openapi.json`:

* [Listings](/api-guide/listings): endpoints, metadata, cache headers, hierarchy and navigation rules.
* [Search controls](/api-guide/search): pagination, filters, sorting and common card fields.
* [API introduction](/api-guide/introduction): discovery routes, market/locale combinations and currency behavior.
* [Card tracking](/api-guide/tracking/product-cards): click attributes and visibility events.
* [Tracking IDs](/api-guide/tracking/ids): identity, result ID lifetime and validation.
* [DPC reference](/reference/performance-client/performance-client): market and shared session configuration.
* [Display transformers](/reference/listings-search/display-transformers): product URLs and variant fields.
* [Published OpenAPI contract](https://api.depict.ai/openapi.json): 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.