Documentation

Quick Start

Register to get a gii_ API key, then include it in every request.

curl -X POST https://api.supermarketpuzzle.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{ "name": "MyAgent", "description": "Meal planning assistant" }'

# Response:
# { "ok": true, "data": { "agent_id": "...", "api_key": "gii_..." } }

curl -X POST https://api.supermarketpuzzle.com/v1/products/search \
  -H "Authorization: Bearer gii_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "high protein greek yogurt without seed oils",
    "filters": { "has_seed_oils": false, "high_protein": true },
    "limit": 5
  }'

Or use the CLI: npx supermarket-puzzle-cli register --name "MyAgent" --description "..."

For the full agent workflow, read the skill file.

Endpoints

All endpoints require Authorization: Bearer gii_... except /register.

POST /products/search

Semantic product search. Natural language query embedded via OpenAI, matched against 18,000+ products in Pinecone. Costs one search credit.

{
  "query": "keto snacks for road trips under $5",
  "filters": {
    "keto_friendly": true,
    "maxPrice": 5
  },
  "limit": 10
}

Parameters

Response (each result)

Each result includes score (0–1 relevance),id, and a product object with: brand, product_name, price, size_oz, store_tag, nova_score, reason, subcategory, ingredients, narrative_card, occasions, emotional_tags, image_url, and all 27 knowledge graph flags as booleans.

POST /products/filter

Pure metadata filter. No embedding call — faster and cheaper. Does not count as a search credit.

{
  "filters": {
    "vegan": true,
    "has_seed_oils": false,
    "store_tag": "wholefoods"
  },
  "limit": 20
}

At least one filter is required. Returns the same product shape as search but without a semantic relevance score.

GET /products/{id}

Full product record by ID. Returns everything: nutrition panel with %DV, tokenized ingredients, flagged ingredients with typed categories and reasons, NOVA score with reasoning, all dietary flags, narrative card, occasions, vibes, price, store, size, and image URL.

curl https://api.supermarketpuzzle.com/v1/products/abc123 \
  -H "Authorization: Bearer gii_..."

GET /flags — Available Filters

Returns all 27 knowledge graph flags grouped by category. Use this to discover what filters exist before building queries.

Collections

curl https://api.supermarketpuzzle.com/v1/collections/snacks-without-seed-oils \
  -H "Authorization: Bearer gii_..."

Browse — Stores & Brands

POST /feedback — Report Issues

When something doesn't work, report it. Feedback directly drives what gets built next. All reports are visible at /iterate.

{
  "type": "bug",
  "message": "Search for 'organic milk' returns 0 results, but filtering with dairy_free=false finds milk products.",
  "endpoint": "/v1/products/search",
  "request_body": { "query": "organic milk", "limit": 10 },
  "response_body": { "results": [], "count": 0 },
  "severity": "high",
  "context": "User was building a weekly grocery list"
}

Fields

Response Format

Every response uses this envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "latency_ms": 142,
    "rate_limit": { "remaining": 58, "reset": 1711234567 }
  }
}

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "retry_after": 12
  }
}

Error codes: unauthorized, invalid_request, rate_limited, not_found, internal_error.

Rate Limits

CLI — supermarket-puzzle-cli

Command-line interface that mirrors the full API surface. Install globally or run via npx.

npm install -g supermarket-puzzle-cli

# or run without installing:
npx supermarket-puzzle-cli search "organic snacks"

Commands

Global Flags

Filter Flags

The filter command accepts these flags:

Config

After register, your API key is saved to ~/.config/supermarket-puzzle-cli/config.json. You can also pass --api-key on any command to override it.