Skip to main content

API Endpoints Reference

API Endpoints

Customer-facing API surface grouped by domain, with implemented paths only.

Audience: Integration engineers who need one authoritative endpoint index.

Critical: Base URL: https://api.selwise.com/api/v1. All non-public endpoints require Bearer authentication.

Auth and PermissionsEvent TypesErrors and RetriesCurrency Management

Who This Page Is For

Use this page as a navigation index for implemented, customer-facing endpoints across modules, analytics, integrations, AI, and public runtime APIs.

Quick Start (2-5 Minutes)

1

Pick API domain

Find endpoint group by module or workflow.

Modules | Analytics | Integrations | AI | Public Runtime | Reference Helpers
2

Confirm auth model

Use Bearer auth for private routes; siteKey + public guard for runtime routes.

See /reference/auth-permissions and /reference/security-rate-limits.
3

Use canonical paths

Copy paths exactly; avoid legacy/outdated route aliases.

All routes below are from implemented controllers.
4

Validate with smoke calls

Run one read and one write endpoint in staging before production rollout.

Example: GET config + POST create/update path.
5

Instrument errors and retries

Adopt retry/idempotency strategy for tracked and revenue-impacting paths.

See /reference/errors-and-retries.

Required Fields / Minimum Payload

FieldRequiredTypeUsed by eventsDescription
AuthorizationConditionalBearer tokenAll private endpointsRequired for authenticated API domains.
siteIdConditionaluuidSite-scoped private endpointsMost module/integration analytics routes are site-scoped.
siteKeyConditionalstringPublic runtime endpointsPublic route identifier validated by guard layer.
Content-TypeConditionalapplication/jsonPOST/PUT/PATCH endpointsRequired for JSON payload parsing and validation.

Event or Endpoint Decision Matrix

ScenarioUse ThisWhy
Need module CRUD endpoint quicklyUse Modules section belowFast lookup by business domain.
Need customer-owned SMTP sendingUse Email Marketing routes in Modules sectionCovers sender onboarding, campaign send, and provider events.
Need analytics deep-dive routeUse Analytics section belowIncludes overview, funnels, journeys, cohorts, revenue, etc.
Need channel forwarding setupUse Integrations section belowProvider + webhook + data-layer endpoints grouped together.
Need runtime storefront contractsUse Public Runtime section belowAll siteKey public APIs in one list.
Need permissions/rate-limit contextSee linked reference pagesAvoids auth and throttling surprises.

Auth

POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/login/verify-mfa
POST /api/v1/auth/refresh
GET  /api/v1/auth/csrf
POST /api/v1/auth/logout
POST /api/v1/auth/revoke
GET  /api/v1/auth/mfa/status
POST /api/v1/auth/mfa/setup
POST /api/v1/auth/mfa/verify
POST /api/v1/auth/mfa/enable
POST /api/v1/auth/mfa/disable
POST /api/v1/auth/mfa/backup-codes/regenerate
POST /api/v1/auth/verify-email
POST /api/v1/auth/resend-verification
GET  /api/v1/auth/verification-status

Sites

POST /api/v1/sites
GET  /api/v1/sites
GET  /api/v1/sites/feeds-summary
GET  /api/v1/sites/:id
PUT  /api/v1/sites/:id
GET  /api/v1/sites/:id/stats
POST /api/v1/sites/:id/verify-domain
DELETE /api/v1/sites/:id
GET  /api/v1/sites/:id/predictive-thresholds
PUT  /api/v1/sites/:id/predictive-thresholds
GET  /api/v1/sites/:id/predictive-thresholds/stats
POST /api/v1/sites/:id/predictive-thresholds/calculate
GET  /api/v1/sites/:id/tracking-config
PUT  /api/v1/sites/:id/tracking-config
GET  /api/v1/sites/:siteId/public-api-keys
POST /api/v1/sites/:siteId/public-api-keys
POST /api/v1/sites/:siteId/public-api-keys/:keyId/rotate
POST /api/v1/sites/:siteId/public-api-keys/:keyId/revoke

Currency Contract Updates (v2)

  • Site create/update endpoints accept currency (ISO-4217 uppercase).
  • Product APIs return currency as required field.
  • Category conversion analytics returns metrics.revenueByCurrency[] instead of single scalar mixed totals.

Modules

# Widgets
POST /api/v1/widgets
GET  /api/v1/widgets
GET  /api/v1/widgets/:id
PUT  /api/v1/widgets/:id
POST /api/v1/widgets/:id/toggle-status
POST /api/v1/widgets/:id/duplicate
DELETE /api/v1/widgets/:id

# Campaigns
POST /api/v1/campaigns
GET  /api/v1/campaigns
GET  /api/v1/campaigns/:id
PUT  /api/v1/campaigns/:id
POST /api/v1/campaigns/:id/publish
POST /api/v1/campaigns/:id/pause
POST /api/v1/campaigns/:id/activate
POST /api/v1/campaigns/:id/clone
DELETE /api/v1/campaigns/:id

# Email Marketing (SMTP-first)
POST   /api/v1/email/senders
GET    /api/v1/email/senders
GET    /api/v1/email/senders/:id
PUT    /api/v1/email/senders/:id
POST   /api/v1/email/senders/:id/test
POST   /api/v1/email/senders/:id/verify
POST   /api/v1/email/senders/:id/set-default
DELETE /api/v1/email/senders/:id
POST   /api/v1/email/campaigns
GET    /api/v1/email/campaigns
GET    /api/v1/email/campaigns/:id
PUT    /api/v1/email/campaigns/:id
POST   /api/v1/email/campaigns/:id/cancel
GET    /api/v1/email/provider-connectors
POST   /api/v1/email/provider-connectors
PUT    /api/v1/email/provider-connectors/:id
DELETE /api/v1/email/provider-connectors/:id
GET    /api/v1/email/provider-connectors/:id/health
GET    /api/v1/email/suppressions
POST   /api/v1/email/suppressions
POST   /api/v1/email/suppressions/:id/lift
GET    /api/v1/email/audience/contacts
POST   /api/v1/email/audience/preview
POST   /api/v1/email/audience/sync-users
GET    /api/v1/email/public-api-keys
POST   /api/v1/email/public-api-keys
POST   /api/v1/email/public-api-keys/:id/rotate
POST   /api/v1/email/public-api-keys/:id/revoke
POST   /api/v1/email/providers/:provider/events

# Recommendations
GET    /api/v1/recommendations/strategies
GET    /api/v1/recommendations/platforms
GET    /api/v1/recommendations
GET    /api/v1/recommendations/site/:siteId
GET    /api/v1/recommendations/:id
GET    /api/v1/recommendations/:id/site/:siteId
POST   /api/v1/recommendations/:id/site/:siteId/preview
GET    /api/v1/recommendations/:id/site/:siteId/analytics
POST   /api/v1/recommendations/site/:siteId
PUT    /api/v1/recommendations/:id
PUT    /api/v1/recommendations/:id/site/:siteId
POST   /api/v1/recommendations/:id/duplicate
POST   /api/v1/recommendations/:id/site/:siteId/duplicate
DELETE /api/v1/recommendations/:id
DELETE /api/v1/recommendations/:id/site/:siteId
PUT    /api/v1/recommendations/:id/site/:siteId/toggle-active
PATCH  /api/v1/recommendations/:id
POST   /api/v1/recommendations/site/:siteId/track/event
POST   /api/v1/recommendations/site/:siteId/track/behavior

# Search
GET  /api/v1/search/configs
GET  /api/v1/search/config/:siteId
PUT  /api/v1/search/config/:siteId
POST /api/v1/search/:siteId/reindex
GET  /api/v1/search/:siteId/stats
GET  /api/v1/search/:siteId/products
GET  /api/v1/search/:siteId/categories
GET    /api/v1/sites/:siteId/search/analytics/queries
GET    /api/v1/sites/:siteId/search/analytics/funnel
GET    /api/v1/sites/:siteId/search/analytics/products
GET    /api/v1/sites/:siteId/search/analytics/zero-results
POST   /api/v1/sites/:siteId/search/analytics/zero-results/:queryId/resolve
GET    /api/v1/sites/:siteId/search/analytics/synonyms
POST   /api/v1/sites/:siteId/search/analytics/synonyms
PUT    /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId
DELETE /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId
GET    /api/v1/sites/:siteId/search/analytics/redirects
POST   /api/v1/sites/:siteId/search/analytics/redirects
PUT    /api/v1/sites/:siteId/search/analytics/redirects/:redirectId
DELETE /api/v1/sites/:siteId/search/analytics/redirects/:redirectId
GET    /api/v1/sites/:siteId/search/analytics/boost-rules
POST   /api/v1/sites/:siteId/search/analytics/boost-rules
PUT    /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId
DELETE /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId

# Segments
POST /api/v1/segments
GET  /api/v1/segments
GET  /api/v1/segments/templates
POST /api/v1/segments/templates/:templateId
GET  /api/v1/segments/:id
PATCH /api/v1/segments/:id
DELETE /api/v1/segments/:id
POST /api/v1/segments/:id/evaluate
POST /api/v1/segments/:id/compute-size
POST /api/v1/segments/preview-size
POST /api/v1/public/segments/evaluate
GET  /api/v1/segments/:id/members
POST /api/v1/segments/:id/members
DELETE /api/v1/segments/:id/members/:visitorId
POST /api/v1/segments/:id/members/bulk
POST /api/v1/public/segments/evaluate

# Experiments
POST   /api/v1/experiments
GET    /api/v1/experiments
GET    /api/v1/experiments/:id
PUT    /api/v1/experiments/:id
POST   /api/v1/experiments/:id/start
POST   /api/v1/experiments/:id/pause
POST   /api/v1/experiments/:id/complete
GET    /api/v1/experiments/:id/results
DELETE /api/v1/experiments/:id
GET    /api/v1/public/experiments/assign
POST   /api/v1/public/experiments/track
POST   /api/v1/public/experiments/track-event

# Scripts
POST   /api/v1/scripts
PATCH  /api/v1/scripts/:id
DELETE /api/v1/scripts/:id
GET    /api/v1/scripts
GET    /api/v1/scripts/:id
POST   /api/v1/sites/:siteId/scripts
GET    /api/v1/sites/:siteId/scripts
PATCH  /api/v1/sites/:siteId/scripts/:id
DELETE /api/v1/sites/:siteId/scripts/:id

Analytics

GET  /api/v1/analytics/overview
GET  /api/v1/analytics/activity-logs
GET  /api/v1/analytics/dashboard-summary
GET  /api/v1/analytics/events/breakdown
POST /api/v1/analytics/track
POST /api/v1/analytics/track/batch
GET  /api/v1/analytics/journeys/:siteId
GET  /api/v1/analytics/journeys/:siteId/stats
GET  /api/v1/analytics/journeys/:siteId/funnel
GET  /api/v1/analytics/journeys/:siteId/export
GET  /api/v1/analytics/journeys/:siteId/:journeyId
GET  /api/v1/analytics/correlations/:siteId
GET  /api/v1/analytics/events/:eventId/attribution
GET  /api/v1/analytics/event-sequences/:siteId/insights
GET  /api/v1/analytics/event-sequences/:siteId/raw
GET  /api/v1/analytics/funnels/:siteId
POST /api/v1/analytics/funnels/definitions
GET  /api/v1/analytics/funnels/definitions/site/:siteId
GET  /api/v1/analytics/funnels/definitions/:id
PUT  /api/v1/analytics/funnels/definitions/:id
DELETE /api/v1/analytics/funnels/definitions/:id
POST /api/v1/analytics/funnels/definitions/:id/duplicate
GET  /api/v1/analytics/funnels/definitions/site/:siteId/templates
GET  /api/v1/analytics/funnels/definitions/:id/analyze
GET  /api/v1/analytics/funnels/:siteId/export
GET  /api/v1/analytics/funnels/:siteId/steps/:eventName/export
GET  /api/v1/analytics/cohort/:siteId
GET  /api/v1/analytics/cohort/:siteId/export
POST /api/v1/analytics/cohort/:siteId/cache/rebuild
GET  /api/v1/analytics/product/:siteId/catalog
GET  /api/v1/analytics/product/:siteId/overview
GET  /api/v1/analytics/product/:siteId/associations
GET  /api/v1/analytics/product/:siteId/dwell-time
GET  /api/v1/analytics/product/:siteId/tracking-status
GET  /api/v1/analytics/product/:siteId/top
GET  /api/v1/analytics/category/:siteId/overview
GET  /api/v1/analytics/category/:siteId/top
GET  /api/v1/analytics/category/:siteId/conversion
GET  /api/v1/analytics/category/:siteId/products
GET  /api/v1/analytics/category/:siteId/paths
GET  /api/v1/analytics/category/:siteId/trends
GET  /api/v1/analytics/category/:siteId/filters
GET  /api/v1/analytics/category/:siteId/all
GET  /api/v1/analytics/search/top-queries
GET  /api/v1/analytics/search/top-products
GET  /api/v1/analytics/search/zero-results
GET  /api/v1/analytics/consent/:siteId/stats
GET  /api/v1/analytics/consent/:siteId/trends
GET  /api/v1/analytics/consent/:siteId/impact
GET  /api/v1/analytics/consent/:siteId/categories
POST /api/v1/analytics/consent/:siteId/simulate
GET  /api/v1/analytics/consent/:siteId/export
GET  /api/v1/analytics/consent/compare
GET  /api/v1/analytics/sites/:siteId/datalayer/events
GET  /api/v1/analytics/sites/:siteId/events/types
GET  /api/v1/analytics/sites/:siteId/events
GET  /api/v1/analytics/sites/:siteId/metrics
GET  /api/v1/analytics/sites/:siteId/events/timeseries
GET  /api/v1/analytics/sites/:siteId
GET  /api/v1/analytics/revenue/overview
GET  /api/v1/analytics/revenue/campaigns/:id
GET  /api/v1/analytics/revenue/widgets/:id
GET  /api/v1/analytics/revenue/recommendations/:id
GET  /api/v1/analytics/recommendations/breakdown
GET  /api/v1/analytics/identity/conversion-metrics

Notes:

  • GET /api/v1/analytics/correlations/:siteId supports optional startDate and endDate (ISO timestamp) query params to filter conversion events.
  • GET /api/v1/analytics/events/:eventId/attribution now returns conversionEventAt, totalTouchpoints, and totalInteractions in the primary response contract.
  • GET /api/v1/analytics/events/:eventId/attribution no longer returns totalTouches.

Integrations

GET    /api/v1/sites/:siteId/integrations
GET    /api/v1/sites/:siteId/integrations/health
GET    /api/v1/sites/:siteId/integrations/:provider
PUT    /api/v1/sites/:siteId/integrations/:provider
DELETE /api/v1/sites/:siteId/integrations/:provider
POST   /api/v1/sites/:siteId/integrations/:provider/test
GET    /api/v1/sites/:siteId/integrations/:provider/logs
GET    /api/v1/sites/:siteId/integrations/:provider/mappings
GET    /api/v1/sites/:siteId/integrations/data-layer
PUT    /api/v1/sites/:siteId/integrations/data-layer
POST   /api/v1/sites/:siteId/integrations/data-layer/test
GET    /api/v1/sites/:siteId/integrations/data-layer/events
GET    /api/v1/sites/:siteId/integrations/data-layer/stats
DELETE /api/v1/sites/:siteId/integrations/data-layer
GET    /api/v1/sites/:siteId/integrations/webhooks
POST   /api/v1/sites/:siteId/integrations/webhooks
GET    /api/v1/sites/:siteId/integrations/webhooks/:webhookId
PUT    /api/v1/sites/:siteId/integrations/webhooks/:webhookId
DELETE /api/v1/sites/:siteId/integrations/webhooks/:webhookId
POST   /api/v1/sites/:siteId/integrations/webhooks/:webhookId/test
GET    /api/v1/sites/:siteId/integrations/webhooks/:webhookId/logs

AI

POST /api/v1/ai/generate-text
GET  /api/v1/ai/insights/:campaignId
POST /api/v1/ai/generate-html
POST /api/v1/ai/generate-strategy
GET  /api/v1/ai/sites/:siteId/personalization-config
PUT  /api/v1/ai/sites/:siteId/personalization-config
POST /api/v1/ai/sites/:siteId/sync-embeddings
GET  /api/v1/ai/sites/:siteId/embedding-stats
POST /api/v1/ai/sites/:siteId/calculate-user-profiles
GET  /api/v1/ai/sites/:siteId/sync-progress
GET  /api/v1/ai/sites/:siteId/performance

Product Card Definitions

GET    /api/v1/product-card-definitions/templates
GET    /api/v1/product-card-definitions/product-fields
GET    /api/v1/product-card-definitions/site/:siteId
GET    /api/v1/product-card-definitions/:id/site/:siteId
POST   /api/v1/product-card-definitions/site/:siteId
POST   /api/v1/product-card-definitions/site/:siteId/from-template/:templateId
PUT    /api/v1/product-card-definitions/:id/site/:siteId
POST   /api/v1/product-card-definitions/:id/site/:siteId/duplicate
POST   /api/v1/product-card-definitions/:id/site/:siteId/preview
DELETE /api/v1/product-card-definitions/:id/site/:siteId

Public Runtime

GET    /api/v1/public/sites/:siteKey/config
GET    /api/v1/public/sites/:siteKey/tracking-config
POST   /api/v1/public/sites/:siteKey/events/batch
POST   /api/v1/public/sites/:siteKey/metrics
GET    /api/v1/public/sites/:siteKey/campaigns
GET    /api/v1/public/sites/:siteKey/widgets
GET    /api/v1/public/sites/:siteKey/search
GET    /api/v1/public/sites/:siteKey/search-config
GET    /api/v1/public/sites/:siteKey/search/suggestions
POST   /api/v1/public/sites/:siteKey/search/log
POST   /api/v1/public/sites/:siteKey/search/click
POST   /api/v1/public/sites/:siteKey/search/zero-results
GET    /api/v1/public/sites/:siteKey/recommendations
POST   /api/v1/public/sites/:siteKey/recommendations/:widgetId/products
POST   /api/v1/public/sites/:siteKey/recommendations/track/event
POST   /api/v1/public/sites/:siteKey/recommendations/track/behavior
GET    /api/v1/public/sites/:siteKey/scripts
POST   /api/v1/public/sites/:siteKey/orders
GET    /api/v1/public/sites/:siteKey/email/open/:token
GET    /api/v1/public/sites/:siteKey/email/click/:token
GET    /api/v1/public/sites/:siteKey/email/unsubscribe?token=...
GET    /api/v1/public/sites/:siteKey/integrations
POST   /api/v1/public/sites/:siteKey/users/identify
POST   /api/v1/public/sites/:siteKey/users/traits
POST   /api/v1/public/sites/:siteKey/consent
DELETE /api/v1/public/sites/:siteKey/consent
GET    /api/v1/public/sites/:siteKey/product-metrics/view-count
GET    /api/v1/public/sites/:siteKey/product-metrics/cart-count
POST   /api/v1/public/sites/:siteKey/product-metrics/batch
POST   /api/v1/public/sites/:siteKey/newsletter
POST   /api/v1/public/sites/:siteKey/newsletter/confirm
GET    /api/v1/public/sites/:siteKey/newsletter/confirm?token=...
POST   /api/v1/public/sites/:siteKey/newsletter/api/subscribe
POST   /api/v1/public/newsletter
POST   /api/v1/public/newsletter/subscribe
POST   /api/v1/public/newsletter/confirm
GET    /api/v1/public/newsletter/confirm?token=...
POST   /api/v1/public/contact
GET    /api/v1/public/pricing

Important runtime tracking notes:

  • POST /api/v1/public/sites/:siteKey/events/batch validates payloads per event. Invalid events are rejected individually, valid events in the same batch are accepted.
  • Deprecated product metadata keys (productId, productSku, sku) are rejected by batch ingestion.
  • Mobile originless runtime requests are supported through scoped key auth (x-selwise-api-key) with method-based scope checks (GET -> mobile_read, write methods -> mobile_write).
  • Mobile SDK metadata headers are x-selwise-client-platform and x-selwise-client-version.
  • Email open/click/unsubscribe tracking endpoints are tokenized and should be called only through renderer-generated URLs.
  • Tenant newsletter endpoints are site-scoped (/public/sites/:siteKey/newsletter/*) and write to tenant audience data; they do not use admin/global newsletter sender configuration.
  • Legacy /public/newsletter* endpoints remain for admin/global newsletter domain.

Public newsletter quick usage:

# Browser/widget
curl -X POST "https://YOUR_API_DOMAIN/api/v1/public/sites/SITE_KEY/newsletter" \
  -H "Content-Type: application/json" \
  -H "Origin: https://store.example.com" \
  -d '{"email":"alice@example.com"}'

# API-only
curl -X POST "https://YOUR_API_DOMAIN/api/v1/public/sites/SITE_KEY/newsletter/api/subscribe" \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_xxxxx" \
  -d '{"email":"alice@example.com","consentGranted":true}'

For full request/response contract and field-level behavior, see:

Common Errors and Fixes

Calling non-implemented endpoint from old docs

Cause: Legacy route references in internal notes.

Fix: Use only this reference and module-specific pages with validated paths.

Public endpoint fails with site/origin error

Cause: siteKey invalid, site unverified, or domain mismatch.

Fix: Verify site setup and origin headers against site domain.

403 on private endpoints

Cause: Missing token or insufficient permission.

Fix: Check auth token validity and role permissions.

429 responses on tracking/order routes

Cause: Visitor/order throttling limits exceeded.

Fix: Implement client backoff and dedup logic; see security/rate-limit reference.

Production Checklist

  • Endpoint usage is sourced from this implemented-path reference only.Required
  • Auth and permission model is documented per integration service.Required
  • Public runtime requests are validated against site/origin constraints.Required
  • Retry and backoff behavior is implemented for 429/5xx responses.Required
  • Release smoke tests include representative private and public endpoints.Required

Next Steps