> ## 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 an integration with an AI agent

> A short agent prompt and reference instructions for a Platform API storefront integration.

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](/api-reference/headless/build-collections-with-ai-agent)
for a migration limited to category and collection pages.

## Agent prompt

```text theme={null}
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](https://docs.depict.ai/api-reference/headless/overview#api-overview)
and `GET https://api.depict.ai/openapi.json`:

* [API introduction](/api-guide/introduction): request conventions, discovery routes, markets, locales and currency.
* [Search](/api-guide/search): results, suggestions, filters, sorting, pagination, product data and errors.
* [Listings](/api-guide/listings): metadata, products, cache headers, hierarchy and navigation rules.
* [Recommendations](/api-guide/recommendations/api): configured types, product context and response fields.
* [DPC setup](/api-guide/tracking/setup): browser initialization.
* [Card tracking](/api-guide/tracking/product-cards): click attributes and visibility events.
* [Tracking IDs](/api-guide/tracking/ids): result IDs, product IDs, transaction IDs and event validation.
* [PDP tracking](/api-guide/tracking/product-pages), [add-to-cart tracking](/api-guide/tracking/add-to-cart) and [purchase tracking](/api-guide/tracking/purchases): event requirements.
* [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.

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.


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