API Documentation

Everything you need to integrate Pulse's real-time inference engine into your platform.

Authentication

Learn how to authenticate your API requests

Base URL

https://thepulseapi.com/v1

How It Works

Pulse personalizes your storefront in three moves: capture anonymous in-session signals, tell us what you sell, then ask us how to order it for the visitor in front of you. The browser SDK handles the first; your backend handles the other two over a simple REST API.

1. Capture signals

Drop in the SDK. It quietly streams anonymous behavior to Pulse in the background. No cookies, nothing personal.

2. Sync your catalog

Push your products and categories so Pulse knows what it can recommend and rank.

3. Fetch personalization

Call the Personalization API to reorder grids and search results for the live visitor.

Quick Start

Add Pulse to your website in three steps. The SDK loads in the background, so it never slows your page down, and it only reads anonymous in-session signals. No cookies, nothing personal.

1. Add the SDK

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

index.html

<!-- 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.

index.html

<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.

product-list.html

<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>

That's it, you're live: The SDK streams anonymous signals (device, referrer, scroll, clicks) to POST /v1/track and Pulse infers the visitor's persona in under 50ms. Call the Inference API below from your backend to personalize search, recommendations, and layout.

Authentication

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.

# Example request with authentication

curl -X GET "https://thepulseapi.com/v1/infer" \

-H "Authorization: Bearer YOUR_API_KEY"

Security Note: Never expose your secret API key in client-side code. All inference and catalog requests should be made from your backend servers. The browser SDK uses a publishable key (pk_live_…) scoped to event ingestion only.

Inference API

POST/v1/infer

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

Target latency: <50ms (p95)

Request Body

request.json

{
  "session_id": "sess_abc123",
  "context": {
    "device": "mobile",
    "browser": "safari",
    "referrer": "instagram.com",
    "geo": { "country": "US", "region": "CA" },
    "time": "2025-01-14T23:30:00Z"
  },
  "behavior": {
    "search_query": "running shoes under 100",
    "filters": ["price:0-100", "rating:4+"],
    "viewed_products": ["prod_123", "prod_456"],
    "dwell_time_ms": 45000
  }
}

Response

200 OK

{
  "persona": {
    "primary": "value_conscious_runner",
    "confidence": 0.89,
    "attributes": {
      "price_sensitivity": "high",
      "brand_loyalty": "low",
      "social_proof_reliance": "high",
      "purchase_intent": "active"
    }
  },
  "recommendations": {
    "product_ids": ["prod_789", "prod_012", "prod_345"],
    "rerank_scores": [0.94, 0.91, 0.87]
  },
  "metadata": {
    "inference_time_ms": 32,
    "model_version": "v2.3.1"
  }
}

Catalog Sync — Products & Categories

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 real-time (under 50ms).

POST/v1/products

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.

POST /v1/products

{
  "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
    }
  ]
}

POST/v1/categories

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.

POST /v1/categories

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

DELETE/v1/products/{id}

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.

Keeping in sync: Most merchants wire these calls to their store's product/category change events (e.g. a Shopify webhook or a save hook in a custom backend) so the Pulse catalog always mirrors what shoppers see. A nightly full re-sync is recommended as a safety net.

Personalization API

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.

POST/v1/recommend

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

POST /v1/recommend

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

200 OK

{
  "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 }
}

POST/v1/search

Re-rank your search results by intent. Send the shopper's query and Pulse orders the matching products by the persona inferred this session. Results are cursor-paginated.

POST /v1/search

{
  "session_id": "sess_abc123",
  "query": "running shoes under 100",
  "filters": ["price:0-100", "rating:4+"],
  "limit": 24
}

200 OK

{
  "results": [
    { "product_id": "prod_789", "score": 0.94 },
    { "product_id": "prod_012", "score": 0.91 }
  ],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "limit": 24
  }
}

Webhooks

Configure webhooks to receive real-time notifications for events like persona updates, conversion tracking, and model improvements.

Available Events

•session.converted — Conversion attributed to Pulse
•products.tagged — Product tagging completed
•model.updated — Inference model improved

Errors

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.

400 Bad Request

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

Common Status Codes

Code	Meaning
400	Bad Request — the payload is malformed or a required field is missing.
401	Unauthorized — the API key is missing or invalid.
403	Forbidden — the key is valid but not permitted for this resource.
404	Not Found — the session, product, or endpoint does not exist.
422	Unprocessable Entity — the request is well-formed but fails validation.
429	Too Many Requests — you have exceeded your plan's rate limit.
500	Server Error — something went wrong on our side; retry with backoff.

Rate Limits

Plan	Inference API	Catalog API
Starter	100 req/sec	10 req/sec
Growth	500 req/sec	50 req/sec
Enterprise	Custom	Custom

SDKs & Libraries

JavaScript / Node.js

npm install @pulse-ai/sdk

Python

pip install pulse-ai

Ruby

gem install pulse-ai

Need Help?

Our solutions engineering team is here to help you integrate Pulse successfully.

Get Integration Support Contact Support