Developer documentation

Authenticate with a bearer key. Customer keys begin with pdi_live_. Never expose a production key in browser-side JavaScript.

Manage subscription

Authentication

Authorization: Bearer pdi_live_...

A key belongs to one API client and one plan. Keys can be revoked independently. PDI stores only a SHA-256 hash of customer keys.

Limits and usage

Successful authentication returns quota headers including X-RateLimit-Plan, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and per-minute equivalents. Monthly exhaustion or minute-rate exhaustion returns HTTP 429.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/usage"

Endpoints

GET /v1/resolve-entity

Resolve a term across grapes, canonical wine geographies, spirits and beer. Required: q. Optional: limit 1–25.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/resolve-entity?q=Barolo&limit=5"

GET /v1/explain

Retrieve the structured PDI profile for the best resolved drink entity.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/explain?q=Barolo"

GET /v1/pair

Retrieve PDI pairing guidance when verified pairing evidence exists. Wine geographies return an explicit boundary when sourced sensory evidence is unavailable.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/pair?q=Pinot%20Noir"

GET /v1/compare

Return two resolved scoped profiles.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/compare?left=Merlot&right=Cabernet%20Sauvignon"

GET /v1/usage

Current plan and monthly usage for the calling API key. This endpoint does not consume quota.

curl -s \
  -H "Authorization: Bearer $PDI_API_KEY" \
  "https://api.pinpointed.dev/v1/usage"

Errors

401 UNAUTHORIZED

Missing, unknown, revoked or inactive key.

429 RATE_LIMITED

Per-minute request limit reached.

429 QUOTA_EXCEEDED

Monthly plan allowance reached.

4xx / 5xx from PDI

The gateway preserves the existing PDI v1 response and error contract and adds a request ID.

Machine-readable specification

Open OpenAPI JSON