API.md

API Reference

All routes are Next.js App Router API routes under src/app/api/.

Auth & User

POST /api/auth/device-login

Implicit device login. Creates a user if the device ID is new.

Body: { deviceId: string }

Response: { token: string } (JWT session cookie set automatically)

GET /api/user/profile

Get current user profile.

Headers: Cookie: session=<jwt>

PATCH /api/user/settings

Update user settings (primary store, location).

Headers: Cookie: session=<jwt>

Scanning

POST /api/scan/analyze-image

Main pipeline. Accepts a base64 image, returns matched items with prices and savings.

Body: { image: string (base64) }

Response:

{
  "items": [
    {
      "name": "string",
      "brand": "string",
      "price": 0.00,
      "bestPrice": 0.00,
      "bestStore": "string",
      "savings": 0.00,
      "matched": true
    }
  ],
  "unmatched": ["string"],
  "totalSavings": 0.00
}

POST /api/scan/resolve-match

Manually resolve an unmatched item to a database product.

Body: { rawText: string, productId: string }

POST /api/scan/shoplist-batch

Batch operations on the shopping list.

Products & Pricing

GET /api/products

Get product catalog.

Query: ?limit=50&offset=0

GET /api/products/search

Fuzzy search products.

Query: ?q=bananas&limit=10

GET /api/pricing

Get prices for a specific product.

Query: ?productId=<id>

GET /api/pricing/compare

Batch price comparison for multiple products.

Query: ?productIds=id1,id2,id3&homeStoreId=<id>

GET /api/pricing/flyer-deals

Get active flyer deals.

Query: ?storeId=<id>&limit=50

Stores

GET /api/stores

Get nearby stores.

Query: ?lat=43.65&lon=-79.38&radius=10

Health

GET /api/health

Health check. Returns { status: "ok" }.

Authentication

Most /api routes (except /api/health, /api/auth/*, and /api/scan/*) require a valid session cookie containing a JWT signed with JWT_SECRET.

The middleware at src/middleware.ts validates the session using jose with HS256.