Custom API

Connect any REST or GraphQL product endpoint to betterfound.ai. If your platform isn't listed in the integration guides, the Custom API option covers it.

Requirements

Your endpoint must:

• Return products as a JSON array (or a JSON object with a known array key)
• Be accessible over HTTPS
• Respond within 30 seconds (betterfound.ai will timeout and retry)

Authentication is optional — betterfound.ai supports:

• No auth (public endpoints)
• Bearer token (Authorization: Bearer <token>)
• API key header (any header name + value)
• Basic auth

Minimum product schema

Each product object must have at minimum:

{
  "id":    "string or number — unique product identifier",
  "name":  "string — product display name",
  "url":   "string — absolute URL to the product page"
}

Recommended additional fields (improve search quality significantly):

{
  "description": "string — full product description",
  "price":       123.45,
  "currency":    "GBP",
  "image_url":   "https://...",
  "category":    "string",
  "vendor":      "string",
  "tags":        ["array", "of", "strings"],
  "in_stock":    true
}

Paginated responses

If your API paginates results, configure the Pagination settings in the data source form:

GraphQL endpoints

For GraphQL, use the GraphQL data source type. Provide your endpoint URL and a query that returns an array of products:

query GetProducts($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    nodes {
      id
      title
      description
      priceRange { minVariantPrice { amount currencyCode } }
      featuredImage { url }
      onlineStoreUrl
    }
    pageInfo { hasNextPage endCursor }
  }
}

Field transforms

In the schema mapping step you can apply simple transforms to fields before they reach betterfound.ai's index:

• Prefix URL — prepend a base URL to relative image paths
• Join array — join an array of strings into a single comma-separated value
• Pick nested — select a nested field using dot notation
• Template — combine fields using a template string, e.g. {name} — {vendor}