🗺️ Find Your Integration Path

The Athos API supports several integration patterns depending on your storefront stack. Before jumping into endpoints, figure out which path fits your setup, as each one has different requirements for what you call directly vs. what's handled for you.

🔀 Integration Types

🔄 Migrating from Searchspring

If you're an existing Searchspring customer migrating to Athos, the endpoint structure and event tracking have changed. Don't start from scratch, use our migration guides to map your existing implementation to the new architecture.

Searchspring to Athos Migration Guide →
Beacon 2.0 Migration Guide →
Both Athos Commerce and Searchspring accounts can use Beacon.js

⚡ API-Only (Custom Frontend)

You're building everything from scratch and calling Athos endpoints directly. This reference is your home base.

Use Search, Autocomplete, Category, and Recommendations endpoints to fetch data
Implement Beacon.js for event tracking
Follow the API Integration Checklist to make sure nothing is missed

🫰 Snap SDK

Snap is Athos's open-source SDK that handles API requests, state management, and optional UI components for you. If you're using Snap, you won't be calling most of these endpoints directly.

Visit the Snap documentation site for setup and configuration
Come back here for anything Snap doesn't cover, including custom endpoints, Indexing, or Personalization edge cases
Beacon tracking is handled by Snap automatically

🛍️ Shopify

If you're on Shopify, use the Shopify Web Pixel extension to handle your beacon events. The Pixel subscribes directly to Shopify Customer Events, replacing the need to manually implement Shopping Platform events for product views, cart, and orders.

Shopify Web Pixel setup →
Still use the Search, Autocomplete, Category, and Recommendations endpoints directly for search and discovery
Still implement beacon events manually for search, autocomplete, and recommendations interactions

🏗️ Headless

You're running a headless storefront (Next.js, Hydrogen, custom React, etc.) and controlling your own rendering layer.

Use all Search, Autocomplete, Category, and Recommendations endpoints for data
Choose your UI approach independently; Snap components work in headless environments, or build your own
Implement Beacon.js via NPM for tracking, as the CDN approach won't work in most SSR setups
For server-side requests, pass the X-Forwarded-For header with the customer's IP address

🌐 Base URLs

API	Base URL
Search, Autocomplete, Category, Product Finder	`https://{siteId}.a.athoscommerce.net/v1`
Personalization (Preflight)	`https://{siteId}.a.athoscommerce.net/v1`
Recommendations	`https://{siteId}.a.p13n.athoscommerce.net/v1`
Beacon Tracking	`https://analytics.athoscommerce.net/beacon/v2`

Replace {siteId} with your unique Athos site ID, found in the Athos Management Console.

🔑 Authentication

Most API endpoints authenticate via your siteId passed as a subdomain in the base URL. No API key header is required for client-side requests.

The Indexing API uses HTTP Basic Auth, using your siteId as the username and your secretKey as the password.

https://[siteId]:[secretKey]@index-api.athoscommerce.net/api/index

🍪 Required Cookies

Set these on every page load before making API calls:

Cookie	Expiration	Purpose
`athosUserId`	1 year	Persistent user identifier
`athosSessionId`	Session	Session identifier

See Athos Cookies for full implementation details.

🗂️ What's in this Reference

Section	Description
Autocomplete	Suggest, trending, and autocomplete endpoints for search-as-you-type
Search	Full search results with filtering, sorting, merchandising, and pagination
Category	Product listing page results powered by Athos
Personalization	Preflight endpoint for personalized search and recommendations
Recommendations	Personalized and bundle product recommendation endpoints
Product Finder	Guided selling and product finder endpoints
Beacon Tracking	Event tracking for analytics, reporting, and personalization
Indexing	Feed submission and indexing status endpoints