API Documentation

1. Add the SDK

Drop this script tag into the head of your page. It loads asynchronously and never blocks rendering.

<!-- Add to your site's <head> -->
<script src="https://cdn.thepulseapi.com/pulse-sdk.min.js" async></script>

2. Initialize

Initialize Pulse with your merchant ID and publishable key (pk_live_…). Automatic signal capture begins immediately.

<script>
  window.addEventListener('DOMContentLoaded', () => {
    Pulse.init({
      merchantId: 'your_merchant_id',
      apiKey: 'pk_live_xxx'
    });
  });
</script>

3. Tag key elements (optional)

Add a data-pulse-track attribute to sort dropdowns, filters, and CTAs to capture high-intent interactions automatically.

<select data-pulse-track="sort_preference">
  <option value="price_low_high">Price: Low to High</option>
  <option value="price_high_low">Price: High to Low</option>
</select>

You'll need a Pulse account first. Sign up to create your organization, then generate and manage your API keys from the dashboard. Sign up to get your API keys →

All API requests require authentication using an API key. Include your key in the Authorization header.

Get real-time persona inference for a visitor session. Returns persona attributes, confidence scores, and recommended product rankings.

Push your products and categories to Pulse so the engine knows what it can personalize. Send a full catalog once, then keep it in sync by sending each create, update, or delete as it happens in your store.

Enrichment and Digital Twin tagging run asynchronously in the ingestion pipeline, the upsert call returns 202 Accepted immediately and the products.tagged webhook fires when a product becomes available for inference. Inference itself stays on the request path.

Create or update products. The call is idempotent on id, send the same product again with new fields to update it. Accepts one product or a batch.

{
  "products": [
    {
      "id": "prod_123",
      "name": "Performance Running Shoe",
      "description": "Lightweight cushioned trainer for daily runs",
      "price": 129.99,
      "category_id": "cat_running_shoes",
      "image_url": "https://...",
      "in_stock": true
    }
  ]
}

Sync your category tree so Pulse understands how products relate. Set parent_id to mirror your store's hierarchy. Upserted the same way as products.

{
  "categories": [
    { "id": "cat_footwear", "name": "Footwear", "parent_id": null },
    { "id": "cat_running_shoes", "name": "Running Shoes", "parent_id": "cat_footwear" }
  ]
}

Remove a product when it is deleted or permanently out of stock. It stops appearing in recommendations immediately. Use the same pattern to delete categories.

Once the SDK is capturing signals and your catalog is synced, call these endpoints to reorder your storefront in real time for the current visitor. Call them from your backend with a Bearer token, passing the session_id the SDK created in the browser.

Return a ranked list of products personalized to the visitor's live persona, use it for "For You" grids, related products, and homepage rails.

{
  "session_id": "sess_abc123",
  "type": "for_you",
  "limit": 12
}

{
  "recommendations": {
    "product_ids": ["prod_789", "prod_012"],
    "rerank_scores": [0.94, 0.91]
  },
  "persona": {
    "primary": "value_conscious_runner",
    "confidence": 0.89
  },
  "metadata": { "inference_time_ms": 28 }
}

Pulse uses standard HTTP status codes and returns errors in the RFC 7807 Problem Details format, so every error includes a machine-readable type and a human-readable detail.

{
  "type": "https://thepulseapi.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "session_id is required",
  "instance": "/v1/recommend"
}