API Reference

ShelfWise API Reference

The ShelfWise backend exposes a FastAPI REST API. All endpoints are served from the root path by default (http://localhost:8000).

Content Types

• application/json for most requests and responses
• multipart/form-data for CSV uploads
• text/event-stream for job progress streams

Endpoints

App & Health

GET /

Returns app info, version, and a list of available endpoints.

GET /app

Serves the frontend single-page application.

GET /api/health

Health check with feature flags, scraper counts, and cache stats.

{
  "status": "ok",
  "version": "1.0.0",
  "scrapers": 10,
  "registry_sources": 271,
  "cache_size": 42
}

Batch Processing

GET /api/demo

Loads 3 demo products without scraping.

POST /api/batch

Submit a list of UPCs for processing.

Request body:

{
  "upcs": ["049000050088", "038000183005"],
  "auto_scrape": true
}

Response:

{
  "job_id": "abc123",
  "total": 2,
  "queued": 2,
  "running": 0,
  "completed": 0,
  "failed": 0
}

POST /api/upload-csv

Upload a CSV file with a required upc column.

Form field: file

Response: job status object.

Jobs

GET /api/jobs/{job_id}

Get current job status.

GET /api/jobs/{job_id}/stream

Server-Sent Events stream of live job updates. Connect from the browser or any SSE client.

Products

GET /api/products

List enriched products.

POST /api/products/{upc}/images

Upload a product image. Saved to backend/uploads/ and attached to the product record.

Form field: file (image: jpg, png, webp, gif)

Response:

{
  "upc": "123456789012",
  "image_url": "/uploads/123456789012_abc123.jpg",
  "images": [...]
}

DELETE /api/products/{upc}/images

Remove an image from a product record and delete the uploaded file if it is local.

Query parameter: url — the image URL to remove

Image Search

Query parameters:

Parameter	Type	Description
q	string	Full-text search by name or UPC
brand	string	Filter by brand
category	string	Filter by category
status	string	Filter by status (complete, partial, error)
min_confidence	float	Minimum confidence score (0–1)
limit	int	Page size
offset	int	Pagination offset

GET /api/products/{upc}

Get a single consolidated product.

GET /api/products/{upc}/compare

Compare the consolidated record with raw source notes.

Image Search

The pipeline automatically uses name-based image search as a fallback when no verified images are found for a UPC (especially useful for local PLUs). The backend/image_search.py module tries, in order:

1. Brave Images API (requires BRAVE_API_KEY)
2. Google Custom Search (requires GOOGLE_API_KEY + GOOGLE_CX)
3. DuckDuckGo Images (no API key)
4. Bing Images (no API key)

Search & Stats

GET /api/search

Full-text search across product names and UPCs.

GET /api/stats

Portfolio analytics: total products, confidence distribution, status breakdown, top brands/categories.

GET /api/metrics

Performance metrics for scrapers and reasoning engine.

Export

POST /api/export

Export the current portfolio, optionally filtered.

Request body:

{
  "format": "csv",
  "status": "complete",
  "min_confidence": 0.7,
  "q": "coca",
  "preview": false,
  "preview_limit": 5
}

Supported formats: csv, json, shopify, amazon, woocommerce, ebay, etsy, bigcommerce, doordash, ubereats, grubhub.

Filters:

Field	Description
status	Only export products with this status (complete, partial, error)
min_confidence	Only export products with confidence >= this value
q	Search query matched against name, brand, category, UPC
preview	If true, return a JSON preview instead of a file
preview_limit	Number of products to include in preview (default 5, max 50)

Response: downloadable file, or JSON preview when preview: true.

Foundry IQ

GET /api/foundry/health

Foundry IQ service health.

POST /api/foundry/query

Natural-language knowledge query.

POST /api/foundry/reason

Reason about a specific UPC.

GET /api/foundry/ontology

Export product ontology.

GET /api/foundry/graph/search

Semantic search over the knowledge graph.

GET /api/foundry/graph/related/{node_id}

Get related graph nodes.

GET /api/foundry/history

Query history.

POST /api/foundry/ingest

Force re-ingestion of the product catalog into the knowledge graph.

Utilities

POST /api/clear

Clear all products and jobs.

Data Models

ConsolidatedProduct

{
  "upc": "049000050088",
  "name": "Coca-Cola Classic 12 Pack",
  "brand": "Coca-Cola",
  "category": "Beverages",
  "description": "12-pack of 12 fl oz cans...",
  "image_url": "https://example.com/image.jpg",
  "images": [...],
  "attributes": {"size": "12 fl oz", "pack": "12"},
  "confidence": 0.92,
  "status": "complete",
  "citations": [...],
  "reasoning_trace": [...],
  "foundry_enriched": false,
  "foundry_sdk": null
}

JobStatus

{
  "job_id": "abc123",
  "total": 10,
  "queued": 0,
  "running": 2,
  "completed": 7,
  "failed": 1,
  "created_at": "2026-06-14T17:00:00Z",
  "updated_at": "2026-06-14T17:05:00Z"
}

SDK & Client Generation

FastAPI serves an interactive OpenAPI UI at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Use the OpenAPI schema to generate clients in TypeScript, Python, Go, etc.