{"openapi":"3.1.0","info":{"title":"Pinpointed Drinks Intelligence API","version":"1.0.0-early-access","description":"Evidence-backed wine, spirits and beer intelligence. Coverage is explicit: unavailable evidence is not silently invented."},"servers":[{"url":"https://api.pinpointed.dev"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"security":[],"summary":"Gateway and PDI engine health","responses":{"200":{"description":"Healthy"},"503":{"description":"Gateway or engine unavailable"}}}},"/v1/resolve-entity":{"get":{"summary":"Resolve a drink entity","parameters":[{"name":"q","in":"query","required":true,"description":"Canonical name, supported alias, style or wine geography to resolve","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Ranked entity matches"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate or quota limit reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/explain":{"get":{"summary":"Retrieve a structured sourced profile","parameters":[{"name":"q","in":"query","required":true,"description":"Drink entity to explain","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Structured PDI profile"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate or quota limit reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/pair":{"get":{"summary":"Retrieve explainable pairing guidance","parameters":[{"name":"q","in":"query","required":true,"description":"Drink entity to pair","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Pairing guidance or explicit knowledge boundary"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate or quota limit reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/compare":{"get":{"summary":"Compare two resolved profiles","parameters":[{"name":"left","in":"query","required":true,"description":"First drink entity","schema":{"type":"string","maxLength":200}},{"name":"right","in":"query","required":true,"description":"Second drink entity","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Two scoped PDI profiles"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate or quota limit reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/demo/resolve-entity":{"get":{"security":[],"summary":"Public keyless demo of /v1/resolve-entity","description":"Rate limited per IP. Results are capped and may be served from a short-lived cache.","parameters":[{"name":"q","in":"query","required":true,"description":"Canonical name, supported alias, style or wine geography to resolve","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Ranked entity matches"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Demo rate limit reached","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Demo disabled or daily cap reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/demo/explain":{"get":{"security":[],"summary":"Public keyless demo of /v1/explain","description":"Rate limited per IP. May be served from a short-lived cache.","parameters":[{"name":"q","in":"query","required":true,"description":"Drink entity to explain","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Structured PDI profile"},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Demo rate limit reached","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Demo disabled or daily cap reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/demo/pair":{"get":{"security":[],"summary":"Public keyless demo of /v1/pair","description":"Rate limited per IP. May be served from a short-lived cache.","parameters":[{"name":"q","in":"query","required":true,"description":"Drink entity to pair","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Pairing guidance or explicit knowledge boundary"},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Demo rate limit reached","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Demo disabled or daily cap reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/demo/compare":{"get":{"security":[],"summary":"Public keyless demo of /v1/compare","description":"Rate limited per IP. May be served from a short-lived cache.","parameters":[{"name":"left","in":"query","required":true,"description":"First drink entity","schema":{"type":"string","maxLength":200}},{"name":"right","in":"query","required":true,"description":"Second drink entity","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Two scoped PDI profiles"},"404":{"description":"Entity not resolved","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Demo rate limit reached","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Demo disabled or daily cap reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/usage":{"get":{"summary":"Read plan and current monthly usage","responses":{"200":{"description":"Plan, usage and remaining allowance"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"PDI API key"}}}}