Skip to main content

​
API overview

Depict exposes two APIs, each with a different audience:

Portal API

The REST API behind the merchant portal. Manage merchants, products, collections and curation, and read the metrics and analytics that power the portal dashboards: collection metrics, dead stock, pinned-vs-auto performance, merchant-wide analytics and search insights.

Platform API

The public product-discovery API served from api.depict.ai. Fetch search results, query suggestions, product listings and recommendations, and send tracking events from your storefront.

​
Authentication

Portal API endpoints require a bearer token issued by Depict’s Auth0 tenant. Requests are authorized per merchant: the authenticated user must have access to the merchant_id in the path.
Platform API endpoints identify your shop through the merchant and market parameters that are part of each request body or query string. They are designed to be called directly from the browser.

​
Build a storefront integration

Use the Platform API at https://api.depict.ai for storefront requests. Build new integrations with /v3 serving endpoints. Send merchant, market and locale as specified by each endpoint. The market and locale discovery endpoints require only merchant. Start with Build an integration with an AI agent for a prompt you can adapt to your store. Use Build collection pages with an AI agent when you only want to replace category and collection pages. Read each integration guide with the generated endpoint reference. The guides explain filter selection, pagination, cache headers, tracking IDs and errors. Product display fields and recommendation types depend on your merchant configuration. The reference does not supply a complete product card schema for every merchant.

​
Conventions

  • All endpoints accept and return JSON unless noted otherwise.
  • Time ranges on metrics endpoints use Unix timestamps (start_timestamp, end_timestamp). When omitted, most metrics endpoints default to the last 30 days compared against the previous 30 days.
  • Metric values that compare against a previous period return a value together with a delta_pct (relative change) or delta_pts (percentage-point change for rates such as CTR).