API Reference

Everything you need to integrate Regor AI into your storefront.

Authentication JS Snippet Events API Search API Catalog API Order Tracking Errors Rate Limits

Authentication

Regor uses API keys for authentication. You receive two keys when you sign up:

Publishable Key (pk_live_...)

Safe for browser/client-side use. Used in the JS snippet and for sending events.

Secret Key (sk_live_...)

Server-side only. Used for catalog push, order tracking, and admin operations. Never expose this in browser code.

Include your API key in the X-API-Key header on every request:

bash

curl https://api.regor.ai/v1/search?q=shoes \
  -H "X-API-Key: pk_live_YOUR_KEY"

Dashboard endpoints (settings, billing, audit log) use JWT authentication via HTTP-only cookies, set automatically when you log in.

Signup Response

json

// POST /v1/auth/signup
{
  "token": "eyJ...",
  "tenant_id": "a1b2c3d4-...",
  "api_keys": {
    "publishable_key": "pk_live_...",
    "secret_key": "sk_live_..."
  },
  "message": "Save your API keys now — they won't be shown again."
}

json

// POST /v1/auth/login
{
  "token": "eyJ...",
  "tenant_id": "a1b2c3d4-..."
}

JS Snippet

Add the Regor tracking snippet to your storefront to capture search behavior and optionally replace your native search results.

html

<script
  src="https://api.regor.ai/static/regor.js"
  data-key="pk_live_YOUR_KEY"
  data-mode="collect"
  defer
></script>

Modes

collectObserve only — captures search queries and clicks without modifying your store. Start here.

replaceReplaces your native search results with Regor AI-powered results.

hybridShows Regor results alongside your native results for A/B comparison.

The snippet auto-detects search inputs on your page. No additional configuration is needed for most storefronts.

Events API

Send search and click events to build behavioral signals for AI agents. The JS snippet handles this automatically, but you can also send events directly from your backend.

POST /v1/events

bash

curl -X POST https://api.regor.ai/v1/events \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "search",
    "visitor_id": "v_abc123",
    "session_id": "s_xyz789",
    "query": "blue running shoes",
    "results_count": 12,
    "timestamp": "2025-01-15T10:30:00Z"
  }'

Event Types

search — user performed a search query

click — user clicked a product from search results

add_to_cart — user added a product to cart

purchase — user completed a purchase

Fields

event_type required — one of the types above

visitor_id required — unique visitor identifier

session_id required — current session ID

query — the search query text

product_sku — SKU of the clicked/purchased product

position — position in search results (1-indexed)

results_count — total results returned

timestamp — ISO 8601 timestamp

page_url — URL where the event occurred

Response

Returns HTTP 204 No Content on success (empty body).

Search API

Query the Regor search index directly. Results include AI-powered ranking based on behavioral signals.

GET /v1/search

bash

curl "https://api.regor.ai/v1/search?q=running+shoes&per_page=10" \
  -H "X-API-Key: pk_live_YOUR_KEY"

Query Parameters

q required — search query (1-500 characters)

page — page number (default: 1)

per_page — results per page (default: 20, max: 100)

category — filter by category

available_only — only return in-stock products (true/false)

min_price / max_price — price range filter

Response

json

{
  "query": "running shoes",
  "found": 24,
  "page": 1,
  "hits": [
    {
      "sku": "RS-001",
      "name": "Ultra Boost Running Shoe",
      "category": "Shoes",
      "price": 129.99,
      "available": true,
      "image_url": "https://...",
      "product_url": "https://..."
    }
  ],
  "search_time_ms": 12
}

Catalog API

Push your product catalog to Regor so agents can analyze and optimize your search experience. Requires your secret key.

POST /v1/catalog/upsert

bash

curl -X POST https://api.regor.ai/v1/catalog/upsert \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "id": "SKU-001",
        "sku": "SKU-001",
        "name": "Example Product",
        "category": "Clothing",
        "subcategory": "T-Shirts",
        "price": 29.99,
        "available": true,
        "tags": ["cotton", "casual"],
        "product_url": "https://yourstore.com/products/example",
        "image_url": "https://yourstore.com/images/example.jpg"
      }
    ]
  }'

Required Fields

id — unique product identifier

sku — product SKU

name — product name

category — product category

price — product price (number)

available — in stock (boolean)

product_url — URL to product page

Optional Fields

subcategory — product subcategory

tags — array of string tags

image_url — product image URL

description — product description

Response

json

{
  "indexed": 16,
  "errors": 0,
  "validation_errors": [],
  "collection": "products_abc123",
  "total_submitted": 16,
  "valid": 16
}

CSV Upload

Alternatively, upload your catalog as a CSV file. Requires your secret key.

POST /v1/catalog/upload

bash

curl -X POST https://api.regor.ai/v1/catalog/upload \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -F "file=@products.csv"

CSV Columns

id required — unique product identifier

sku required — product SKU

name required — product name

category required — product category

price required — product price (number)

available required — in stock (true/1/yes)

product_url required — URL to product page

subcategory — product subcategory

image_url — product image URL

description — product description

tags — comma-separated tags

Response

Same shape as the upsert response above.

Order Tracking

Send order data after each purchase to enable real revenue attribution. Without order tracking, revenue is estimated from agent-influenced clicks. Requires your secret key.

POST /v1/orders

bash

curl -X POST https://api.regor.ai/v1/orders \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-1234",
    "total": 89.97,
    "currency": "USD",
    "items": [
      {
        "sku": "SKU-001",
        "name": "Example Product",
        "quantity": 1,
        "price": 29.99
      },
      {
        "sku": "SKU-002",
        "name": "Another Product",
        "quantity": 2,
        "price": 29.99
      }
    ],
    "visitor_id": "v_abc123",
    "session_id": "s_xyz789"
  }'

Fields

order_id required — your order ID (unique)

total required — order total amount

currency — currency code (default: USD)

items required — array of line items (sku, name, quantity, price)

visitor_id — links order to search behavior for attribution

session_id — session in which the purchase occurred

Response

json

{
  "status": "received",
  "order_id": "ORD-1234",
  "line_items_count": 2,
  "attribution": {
    "clicks_matched": 1,
    "attributed_revenue": 29.99,
    "currency": "USD"
  }
}

Once connected, revenue shown across your dashboard will reflect real purchase data instead of click estimates.

Common Errors

All error responses return a JSON object with a detail field describing the issue.

json

{
  "detail": "Invalid API key"
}

HTTP Status Codes

401 Unauthorized — invalid or missing API key

403 Forbidden — endpoint requires a secret key but a publishable key was used

404 Not Found — resource does not exist

429 Too Many Requests — rate limit exceeded (see Rate Limits below)

500 Internal Server Error — server-side failure; contact support if persistent

Rate Limits

Publishable key endpoints — 60 requests/minute (configurable)

Secret key endpoints — 300 requests/minute

Secret key reveal — 5 requests/minute per tenant

When rate-limited, you will receive a 429 response. Wait and retry after the limit window resets (1 minute).

json

{
  "detail": "Rate limit exceeded"
}

Need help? Contact support@regor.ai or visit regor.ai/support