{"openapi":"3.1.1","info":{"title":"upc.dev API","description":"Product intelligence API. Search 10M+ canonical products, decode barcodes, and retrieve risk signals and pricing data aggregated from dozens of authoritative sources.","version":"1.0.0","contact":{"url":"https://upc.dev"}},"servers":[{"url":"https://upc.dev","description":"Production"}],"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","x-oaiMeta":{"name":"upc.dev","group":"product-intelligence","human-readable-name":"upc.dev Product Intelligence"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Command center session token"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key obtained from /v1/auth/register"}},"schemas":{"Error":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string"},"code":{"type":"string"}},"required":["ok","error","code"]},"Product":{"type":"object","properties":{"upc":{"type":"string","example":"049000042566","description":"12-14 digit UPC/EAN barcode"},"name":{"type":"string","example":"Coca-Cola Classic, 12 fl oz"},"brand":{"type":"string","example":"Coca-Cola"},"category":{"type":"string","example":"Beverages, Carbonated Soft Drinks"},"description":{"type":"string"},"image_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EnrichedProduct":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string"},"description":"Opaque source identifiers (authenticated responses only). Public responses omit this field.","example":["source-a","source-b","source-c"]},"prices":{"type":"array","items":{"type":"object","properties":{"marketplace":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string","example":"USD"},"url":{"type":"string","format":"uri"},"captured_at":{"type":"string","format":"date-time"}}}},"risk":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100},"level":{"type":"string","enum":["green","yellow","red"]},"recalls":{"type":"integer"},"complaints":{"type":"integer"},"ip_issues":{"type":"integer"},"details":{"type":"array","items":{"type":"object"}}}},"signals":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"signal_count":{"type":"integer"}}}]},"Signal":{"type":"object","properties":{"id":{"type":"string"},"upc":{"type":"string"},"source":{"type":"string","description":"Opaque source identifier.","example":"source-a"},"signal_type":{"type":"string","enum":["price","recall","safety_alert","litigation","regulatory","tariff","nutrition","filing"]},"value_num":{"type":"number","nullable":true},"value_text":{"type":"string","nullable":true},"captured_at":{"type":"string","format":"date-time"}}},"BarcodeIntelligence":{"type":"object","properties":{"barcode":{"type":"string"},"format":{"type":"string","example":"UPC-A"},"valid":{"type":"boolean"},"authenticity_score":{"type":"number","minimum":0,"maximum":100},"gs1":{"type":"object","properties":{"prefix":{"type":"string"},"company":{"type":"string"},"country":{"type":"string"}}},"flags":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/health":{"get":{"summary":"Service health","description":"Returns service status, version, and uptime.","operationId":"getHealth","tags":["System"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"upc.dev"},"version":{"type":"string","example":"1.0.0"},"uptime":{"type":"number","description":"Process uptime in seconds"}}},"example":{"status":"ok","service":"upc.dev","version":"1.0.0","uptime":3600}}}}}}},"/v1/product/{upc}":{"get":{"summary":"Get product intelligence","description":"Returns full product data for a UPC/EAN barcode. Public requests receive basic product data. Authenticated requests (API key or command center token) receive full intelligence: sources, prices, risk assessment, and signals.","operationId":"getProduct","tags":["Products"],"parameters":[{"name":"upc","in":"path","required":true,"description":"UPC-A (12 digits), EAN-13 (13 digits), or UPC-E (8 digits)","schema":{"type":"string","pattern":"^[0-9]{8,14}$","example":"049000042566"}}],"security":[{},{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Product found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"},"timestamp":{"type":"string","format":"date-time"}}},"example":{"ok":true,"data":{"upc":"049000042566","name":"Coca-Cola Classic, 12 fl oz","brand":"Coca-Cola","category":"Beverages","description":"The original Coca-Cola recipe.","image_url":"https://upc.dev/image/049000042566.jpg","created_at":"2025-01-01T00:00:00Z","updated_at":"2025-03-01T00:00:00Z"},"timestamp":"2025-03-13T12:00:00Z"}}}},"400":{"description":"Invalid UPC format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"summary":"Search products","description":"Full-text search across product names, brands, and UPCs. Returns up to 50 results.","operationId":"searchProducts","tags":["Products"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query (minimum 2 characters). Can be a product name, brand, or UPC.","schema":{"type":"string","minLength":2,"example":"coca-cola"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"}}},"cached":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string"}},"timestamp":{"type":"string","format":"date-time"}}},"example":{"ok":true,"data":{"products":[],"total":0},"cached":false,"sources":["index"],"timestamp":"2025-03-13T12:00:00Z"}}}},"400":{"description":"Query too short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mx/{barcode}":{"get":{"summary":"Barcode intelligence (MX engine)","description":"Decode and validate any barcode. Returns format detection, GS1 prefix decode (manufacturer country/company), check digit validation, and an authenticity score based on database cross-referencing. Public endpoint — no auth required for validation. Authenticated requests add product data and marketplace presence.","operationId":"getMx","tags":["Barcodes"],"parameters":[{"name":"barcode","in":"path","required":true,"description":"Any barcode: UPC-A, UPC-E, EAN-13, EAN-8, Code 128, etc. (6-20 characters)","schema":{"type":"string","minLength":6,"maxLength":20,"example":"049000042566"}}],"security":[{},{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Barcode intelligence","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/BarcodeIntelligence"}}}}}},"400":{"description":"Invalid barcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signals/{upc}":{"get":{"summary":"Signal history","description":"Returns the full signal history for a UPC from the DuckDB omniscience cache. Signals include prices, recalls, regulatory filings, litigation, nutritional data, and more — captured from dozens of authoritative sources over time. **Requires authentication.**","operationId":"getSignals","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"upc","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{8,14}$","example":"049000042566"}},{"name":"days","in":"query","required":false,"description":"Lookback window in days (default: 30, max: 365)","schema":{"type":"integer","minimum":1,"maximum":365,"default":30,"example":30}}],"responses":{"200":{"description":"Signal history","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"signals":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"total":{"type":"integer"},"days":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid UPC","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"summary":"Database statistics","description":"Returns product count and signal statistics. Authenticated users see full stats including source breakdown, signal type distribution, and server metrics.","operationId":"getStats","tags":["System"],"security":[{},{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Statistics","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"products":{"type":"object","properties":{"total":{"type":"integer","example":10000000}}},"signals":{"type":"object","properties":{"total":{"type":"integer"}}}}},"timestamp":{"type":"string","format":"date-time"}}},"example":{"ok":true,"data":{"products":{"total":10000000},"signals":{"total":0}},"timestamp":"2025-03-13T12:00:00Z"}}}}}}},"/v1/auth/register":{"post":{"summary":"Register for API key","description":"Register a new account and receive an API key. Rate limited to prevent abuse.","operationId":"register","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"dev@example.com"},"name":{"type":"string","example":"Jane Developer"}}}}}},"responses":{"200":{"description":"Registration successful","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"api_key":{"type":"string","example":"upc_live_abc123..."},"tier":{"type":"string","example":"free"},"rate_limit":{"type":"integer","example":100}}}}}}}},"400":{"description":"Invalid email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/hunter/status":{"get":{"summary":"Hunter pipeline status (admin-only)","description":"Returns the product-discovery pipeline state: total products, queue backlog, last hunter milestone, grade breakdown (A–F) by intel_score. Part of the /api/hunter/* admin namespace.","tags":["Hunter"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Hunter status snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"total_products":{"type":"integer","example":5669067},"queue":{"type":"object","properties":{"total":{"type":"integer"},"pending":{"type":"integer"},"processing":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"}}},"last_run":{"type":"object","nullable":true},"grades":{"type":"object","properties":{"a_count":{"type":"integer"},"b_count":{"type":"integer"},"c_count":{"type":"integer"},"d_count":{"type":"integer"},"f_count":{"type":"integer"},"avg_score":{"type":"number"}}}}}}}},"401":{"description":"Missing or invalid command token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"tags":[{"name":"Products","description":"Product lookup, search, and intelligence","x-oaiMeta":{"group":"core"}},{"name":"Barcodes","description":"Barcode validation and GS1 decoding","x-oaiMeta":{"group":"core"}},{"name":"Signals","description":"Time-series signals from dozens of authoritative sources","x-oaiMeta":{"group":"core"}},{"name":"Auth","description":"API key management","x-oaiMeta":{"group":"auth"}},{"name":"System","description":"Health and statistics","x-oaiMeta":{"group":"system"}},{"name":"Hunter","x-oaiMeta":{"group":"admin"},"description":"Admin-only hunter / intelligence pipeline endpoints under /api/hunter/*. Gated by an X-Command-Token (or Authorization: Bearer <token>) matched against a command-center token set — stricter than the public X-API-Key path and not reachable from untrusted clients. Full endpoint list: /status, /scores, /scoring, /signals, /enrichment, /discovery, /queue, /sources, /validation, POST /enrich/{upc}, POST /discover, POST /validate/{upc}, POST /sources/health-check. Only /status is expanded here as a canonical example; all others share the same BearerAuth requirement and 401 shape."}]}