API Reference Beta

The betterfound REST API lets you manage tenants, data sources, and enrichment programmatically. All endpoints require an API key and return JSON.

Authentication

Pass your API key in every request:

Authorization: Bearer sk-sm-xxxxxxxxxxxx

API keys are generated in the dashboard under Settings → API Keys. Keys are scoped to a single tenant and can be restricted to specific operations.

Base URL

https://api.betterfound.ai/v1

Endpoints

Products — search

POST /products/search

{
  "query":    "lightweight mirrorless camera for travel",
  "filters":  { "max_price": 1200, "in_stock": true },
  "limit":    10
}

// Response
{
  "products": [ ... ],
  "total":    42,
  "took_ms":  38
}

Products — list

GET /products?page=1&per_page=50

// Response
{
  "data":  [ ... ],
  "total": 1240,
  "page":  1
}

Products — get by ID

GET /products/:id

// Response
{
  "id":          "sku-001",
  "name":        "Canon EOS R5",
  "description": "...",
  "price":       3899.00,
  "currency":    "GBP",
  "image_url":   "https://...",
  "tags":        ["full_frame", "8k_video", "weather_sealed"]
}

Data sources — list

GET /data-sources

// Response
[
  {
    "id":     "ds_abc123",
    "name":   "Shopify main",
    "type":   "shopify",
    "status": "active",
    "last_synced_at": "2026-05-24T10:00:00Z"
  }
]

Enrichment — trigger

POST /data-sources/:id/enrich

// Response
{
  "job_id": "enr_xyz789",
  "status": "queued"
}

// Poll status
GET /enrichment/jobs/:job_id
{
  "status":     "running",
  "progress":   { "done": 45, "total": 120 },
  "started_at": "2026-05-24T10:01:00Z"
}

Widget — session

POST /widget/session

{
  "user_id": "optional-your-user-id"
}

// Response
{
  "session_id": "sess_abc123",
  "expires_at": "2026-05-24T12:00:00Z"
}

Rate limits

Error codes