API overview

Six retrieval surfaces. One API.

Index your catalog, run search across keyword, semantic, image, and document modes, and ground AI answers with citations — all behind a clean REST + GraphQL surface.

Talk to a solutions expert Book a demo

Code examples below are illustrative
Bring-your-own LLM supported
Public + secret API key separation

Indexing

Push products, attributes, and inventory.

// Index a product
await fetch("https://api.scouty.ai/v1/index/products", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${SCOUTY_SECRET_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "TM-GTX-42",
    title: "Trailmaster GTX Waterproof Hiking Boot",
    description: "GORE-TEX waterproof hiking boot...",
    attributes: { color: "brown", size: ["8", "9", "10"] },
    images: ["https://cdn.example.com/tm-gtx-42-hero.jpg"],
    inventory: { available: true, count: 42 },
  }),
});

Code shown is illustrative. The full schema and OpenAPI spec are available to design partners.

Hybrid retrieval in a single call.

// Hybrid product + semantic search
const r = await fetch("https://api.scouty.ai/v1/search", {
  method: "POST",
  headers: { "Authorization": "Bearer ${SCOUTY_PUBLIC_KEY}", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "waterproof hiking boot",
    modes: ["product", "semantic", "document"],
    limit: 10,
    filters: { in_stock: true },
  }),
});
const { results, ai_answer } = await r.json();

Use any combination of product, semantic, image, and document modes. AI answers are returned alongside results when configured for the assistant.

Document upload

PDF, manual, and spec-sheet ingestion.

// Upload a PDF for indexing
const fd = new FormData();
fd.append("file", new Blob([pdfBuffer], { type: "application/pdf" }));
fd.append("metadata", JSON.stringify({ product_id: "TM-GTX-42", kind: "care_guide" }));

await fetch("https://api.scouty.ai/v1/index/documents", {
  method: "POST",
  headers: { "Authorization": "Bearer ${SCOUTY_SECRET_KEY}" },
  body: fd,
});

OCR runs automatically on scanned documents. Indexed pages are searchable and citable.

Image search

Search by image URL or upload.

// Image similarity search
await fetch("https://api.scouty.ai/v1/search/image", {
  method: "POST",
  headers: { "Authorization": "Bearer ${SCOUTY_PUBLIC_KEY}", "Content-Type": "application/json" },
  body: JSON.stringify({
    image_url: "https://cdn.example.com/sample-boot.jpg",
    limit: 12,
  }),
});

AI retrieval

Grounded answers with citations.

// Grounded AI retrieval
await fetch("https://api.scouty.ai/v1/ai/answer", {
  method: "POST",
  headers: { "Authorization": "Bearer ${SCOUTY_SECRET_KEY}", "Content-Type": "application/json" },
  body: JSON.stringify({
    assistant_id: "asst_product_qa",
    question: "Which boots are best for wet trails over multiple days?",
    require_citations: true,
    max_tokens: 220,
  }),
});

Each response includes the answer, a list of source citations (product, document page, asset), and metering information.

Webhooks

Subscribe to catalog and search events.

// Webhook payload (search.zero_result)
{
  "event": "search.zero_result",
  "occurred_at": "2026-04-25T13:42:11Z",
  "store_id": "store_abc",
  "data": {
    "query": "waterproof hiking boot",
    "session_id": "ses_8d2",
    "candidates": []
  }
}

Available events include search.* (queries, zero-results, clicks), index.* (catalog updates), and ai.* (completions, citations).

Example flow

A typical headless integration.

Index your catalog via POST /v1/index/products (one-time backfill + webhook updates).
Optionally upload PDFs and assets via POST /v1/index/documents and /v1/index/assets.
Wire your storefront search bar to POST /v1/search with the modes you need.
Wire your AI assistant to POST /v1/ai/answer.
Subscribe to search.* webhooks for analytics and zero-result triage.
Use the merchant dashboard for synonyms, boosts, merchandising, and analytics — alongside your code.

Get started

Want a developer-focused walkthrough?

A Scouty solutions specialist will run through the API surface for your stack and use case.

Request a free expert-led Search Audit Book a demo