Endpoint Catalog
All paths below are relative to /api/v1. Methods reflect the current platform routes; authorization can further restrict actions by role, permission, ownership, status, and feature capability.
Browser runtime endpoints
These routes accept the SDK's runtime token (Authorization: Bearer <runtime token>), obtained from POST /sdk/bootstrap with the public site ID.
| Method | Path | Purpose |
|---|---|---|
POST | /sdk/bootstrap | Exchange a site ID for a 15-minute, origin-bound runtime token. |
POST | /events/track | Ingest one canonical event. |
POST | /events/batch | Ingest 1–100 events. |
GET | /recommendations | Serve recommendations for the key’s site and request context. |
GET | /overlays/config | Return overlays eligible for the page, device, visitor, and server-derived location. |
POST | /overlay-submissions | Submit capture data from an overlay. |
POST | /partner-attribution/touches | Capture a bounded AWIN/CJ partner touch chain with a runtime token. |
POST | /partner-experiments/assignments | Assign an eligible advertiser session to partner-scoped control/treatment with a runtime token. |
GET | /chatbots/config | Return eligible chatbot widget configuration. |
POST | /chatbots/session | Start or resume a chatbot session. |
POST | /chatbots/message | Execute a chatbot turn synchronously. |
POST | /chatbots/products | Resolve product cards for a chatbot turn. |
GET, POST | /workflow-commands | Poll for and acknowledge workflow browser commands. |
POST | /storefront/search | Run a Smart Search query. |
GET, POST | /storefront/collections/{slug}, /query | Read or query a Smart Collection. |
Secret-key server endpoints
These routes accept a secret API key with the listed permission.
| Method | Path | Permission | Purpose |
|---|---|---|---|
POST | /storefront/search, /storefront/collections/{slug}/query | search:read | Server-side Smart Search, for example for SSR. |
POST | /catalog/syncs, /catalog/syncs/{syncId}/batches, /complete | catalog:write | Push a product catalog in batches. |
POST | /commerce/conversions | commerce:convert | Record authoritative store conversions. |
GET | /storefront-plugin/capabilities | any of profiles:write, commerce:convert, recommendations:read, partner_attribution:touch | Which storefront plugin features this key and site can use, with a reason for each unavailable one. Used by the WooCommerce plugin's connection check. |
POST | /partner-attribution/conversions | partner_attribution:convert | Record partner purchases, adjustments, and cancellations. |
POST | /profile-personalization | profiles:write | Import consented personalization profile fields. |
POST | /first-party/profiles | profiles:write | Import consented customer profiles. |
POST | /profile-tokens | profiles:write | Mint a five-minute token naming the customer signed in to a custom storefront. See Identity and privacy. |
GET, POST | /interactions | events:read, events:track | Read or record product interactions. |
GET, POST | /products/embeddings | product_embeddings:read, product_embeddings:write | Check or prepare product search readiness. |
Workspace and access
These routes require a merchant ID token and the corresponding authorization grant.
| Methods | Paths | Purpose |
|---|---|---|
GET, POST | /sites | List or create sites; site creation returns the public site_id and SDK installation snippet. |
GET, PATCH, DELETE | /sites/{siteId} | Read, update, or soft-delete a site. |
GET, POST | /api-keys | List key metadata or create an additional scoped secret key for a site. |
POST | /api-keys/{keyId}/regenerate | Revoke a key and reveal its replacement once. |
GET, PATCH | /merchants/profile | Read or update your own name and email. |
GET, PATCH | /merchants/business | Read or update the company name, industry, company size, timezone, and phone. |
GET, POST, PATCH | /notifications* | List notifications, mark them read, and manage delivery preferences. |
GET, PATCH | /merchants/preferences | Read or update merchant preferences. |
GET, POST / PATCH, DELETE | /access/roles, /access/roles/{roleId} | List and create custom roles; update or delete one. |
GET / PATCH, DELETE | /access/memberships, /access/memberships/{id} | List members; change roles or remove a member. |
POST / DELETE | /access/invitations, /access/invitations/{id} | Invite by email; revoke an invitation. /resend, /accept, and /resolve complete the flow. |
Products, campaigns, and experiments
| Methods | Paths | Purpose |
|---|---|---|
GET, POST | /products | Search/list or create catalog products. |
GET, PATCH, DELETE | /products/{productId} | Read, update, or delete a product. |
GET, POST | /products/imports* | Start, inspect, complete, cancel, and download errors for CSV imports. |
GET | /products/categories, /products/intent-options | Populate campaign filters and intent targeting. |
GET, POST, PATCH | /products/metafields* | Manage product field definitions, source mappings, usage, and conversion previews. |
GET, POST | /coupons | List imported store coupons or request a refresh. |
GET, POST, PATCH | /goal-plans* | Create, revise, and apply AI goal plans. |
GET, POST, PATCH, DELETE | /recommendation-campaigns* | Manage recommendation campaigns. |
GET, POST, PATCH, DELETE | /overlay-campaigns* | Manage overlay campaigns; duplicate actions use /duplicate. |
GET, POST, PATCH, DELETE | /chatbot-campaigns* | Manage chatbot campaigns; duplicate actions use /duplicate. |
GET | /overlay-templates, /chatbot-templates | Read built-in template catalogs. |
GET, POST | /experiments | List or create canonical recommendation and overlay experiments. |
GET, PATCH | /experiments/{experimentId} | Read or update a canonical experiment draft. |
POST | /experiments/{experimentId}/actions/{action} | Validate, start, pause, resume, complete, cancel winner hold, or archive. |
GET | /experiments/{experimentId}/results, /audit, /automatic-evaluations | Read evidence and immutable history. |
GET, POST | /partner-experiments | List or create partner-scoped Upsurge experience experiments. |
GET, PATCH | /partner-experiments/{experimentId} | Read or transition a partner experiment. |
GET | /partner-experiments/{experimentId}/results | Read intent-to-treat lift, readiness, and segmented results. |
Workflows
| Methods | Paths | Purpose |
|---|---|---|
GET, POST | /workflows | List or create workflows. |
GET, PATCH, DELETE | /workflows/{workflowId} | Read, edit, or delete a workflow. |
POST | /workflows/{workflowId}/publish, /unpublish | Change the published runtime version. |
GET | /workflows/templates | List system and merchant templates. |
POST | /workflows/templates/{templateId}/instantiate | Create a workflow from a template. |
GET | /workflows/runs, /workflows/runs/{runId} | Inspect execution summaries and details. |
POST | /workflows/trigger/campaign-start | Authenticated campaign-start trigger. |
POST | /workflows/trigger/chatbot-handoff | Signed chatbot handoff trigger. |
POST | /workflows/webhooks/{slug...} | Signed or configured public webhook trigger. |
Analytics and conversions
| Method | Paths | Purpose |
|---|---|---|
GET | /analytics/metrics, /timeseries, /top | Core first-party aggregates. |
GET | /analytics/campaign-performance | Normalized product-campaign performance. |
GET | /analytics/overlays, /recommendations | Product-specific aggregates. |
GET | /analytics/ads | Connected advertising insights. |
GET | /analytics/attribution, /analytics/attribution/models | Marketing attribution by observed and modeled methods. |
GET | /analytics/partners | Advertiser observed/settled partner performance, profitability, and reconciliation. |
GET | /analytics/publishers | Publisher clicks, provider orders/commission, content/destination performance, and variance. |
GET, POST, PATCH, DELETE | /analytics/reports* | Saved merchant report definitions. |
GET | /conversions | Conversion records and attribution context. |
GET | /partner-intelligence/context, /reconciliation-cases | Partner Intelligence setup context and open reconciliation cases. |
Customers, audiences, and leads
| Methods | Paths | Purpose |
|---|---|---|
GET, POST, PATCH, DELETE | /customer-profiles* | List, read, edit, suppress, merge, or delete customer profiles. |
GET, POST, PATCH, DELETE | /customer-lists* | Manage static and dynamic customer lists. |
GET, POST, PATCH, DELETE | /cohorts* | Manage audiences, estimate reach, and read audience insights. |
GET, POST, DELETE | /leads* | List and delete leads; /leads/export downloads CSV and POST /leads/retry retries delivery. |
GET | /overlay-submissions/export | Export overlay submissions. |
POST | /partner-attribution/conversions | Ingest authoritative partner purchases, adjustments, and cancellations with a scoped secret key. |
Integrations, media, and search
| Methods | Paths | Purpose |
|---|---|---|
GET, POST, PATCH, DELETE | /integrations/connections* | Create, inspect, rotate, verify, sync, act through, or revoke merchant connections. |
POST, GET | /integrations/oauth/start, /oauth/callback | Begin and finalize provider OAuth with state validation. |
GET, POST, DELETE | /media* | List, upload/import, mark usage, or delete merchant media. |
GET | /media/unsplash/search | Search Unsplash for importable media. |
GET | /search | Search merchant-owned dashboard entities and public docs. |
GET, POST, PATCH | /smart-search/* | Configure, validate, preview, publish, and roll back Smart Search; read suggestions, analytics, and index health. |
POST | /intent/reach-estimate | Estimate scoped campaign reach. |
GET, POST | /intent/audience-memberships/import, /sync | List options or run governed audience membership activation. |
Operational routes
/integrations/jobs/process requires a worker secret. /health is a deployment health surface. Demo configuration and platform admin routes are not stable customer integration contracts.