{"openapi":"3.1.0","info":{"title":"Paz.ai Agentic Store Score API","version":"1.0.0","description":"Scan ecommerce stores and retrieve agent-readiness scores. The API checks discovery, structured data, pricing, cart handoff, and trust signals.","contact":{"name":"Paz.ai","url":"https://paz.ai","email":"hello@paz.ai"}},"servers":[{"url":"https://is-agentic.store","description":"Production"}],"paths":{"/api/scan":{"post":{"summary":"Start a new store scan","description":"Submit a store URL to enqueue a scan. A fresh request returns 202 and a scan ID to poll. A report completed within the previous hour may be returned immediately with 200. Rate limited to 5 requests per minute per IP, with additional edge protections in production.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The store URL to scan (e.g. https://yourstore.com)","example":"https://allbirds.com"}}}}}},"responses":{"200":{"description":"A recently completed report was returned from cache","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["completed"]},"score":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"url":{"type":"string","description":"Path to the report page"}}}}}},"202":{"description":"Scan accepted and queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string","enum":["pending","running"]},"url":{"type":"string","description":"Path to the report page"},"duplicate":{"type":"boolean"}}}}}},"400":{"description":"Invalid URL or request body"},"429":{"description":"Rate limit exceeded"},"503":{"description":"The scan could not be queued"}}}},"/api/scan/{id}":{"get":{"summary":"Get scan status and results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Scan ID returned from POST /api/scan"}],"responses":{"200":{"description":"Scan record with status and optional result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"score":{"type":"integer","nullable":true},"maxScore":{"type":"integer"},"grade":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"report":{"type":"object","description":"Full scan result (present when status=completed)","nullable":true}}}}}},"404":{"description":"Scan not found"}}}},"/api/v1/report":{"get":{"summary":"Get report by URL (read-only)","description":"Retrieve the most recent completed scan result for a given store URL. Does not start a new scan.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"The store URL to look up","example":"https://allbirds.com"}],"responses":{"200":{"description":"Completed scan result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string"},"score":{"type":"integer","nullable":true},"maxScore":{"type":"integer"},"grade":{"type":"string"},"evidenceStatus":{"type":"string","enum":["complete","insufficient_evidence"]},"headline":{"type":"string"},"categories":{"type":"array"},"products":{"type":"array"},"recommendations":{"type":"array"},"taskJourney":{"type":"array"},"evaluatorNotes":{"type":"array"}}}}}},"404":{"description":"No completed scan found for this URL"}}}},"/api/health":{"get":{"summary":"Runtime and persistence health check","responses":{"200":{"description":"Runtime and persistence are healthy"},"503":{"description":"Persistence is unavailable"}}}},"/openapi.json":{"get":{"summary":"This OpenAPI specification","responses":{"200":{"description":"OpenAPI JSON spec","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{}},"security":[]}