Parchment
API overview
Parchment ships stable public catalog and price-index APIs plus the internal route layer that powers the web app.
Parchment is the API and Console layer inside Purveyors. It exposes normalized green coffee catalog data, beta catalog similarity matching, and aggregate market intelligence through small public HTTP contracts plus a broader authenticated product backend. Those surfaces share domain logic, but they do not carry the same compatibility promises.
The stable public catalog contract is GET /v1/catalog. Anonymous requests are supported for public discovery, while API-key requests are the intended production integration path because they carry plan enforcement and X-RateLimit-* usage headers. GET /v1/catalog/{id}/similar is a beta member and paid API route for candidate matching, not a canonical identity claim. GET /v1/price-index is a Parchment Intelligence API-key contract for aggregate price_index_snapshots data only. It does not expose raw supplier rows, CSV exports, alerts, or webhook support. Most /api/* routes exist to power the Purveyors web platform: catalog UI helpers, inventory, roast workflows, sales tracking, AI chat, workspaces, billing, and admin tooling.
Surface map
Treat the API model as two layers. /v1/* is the public namespace for external integrations. /api/* is the first-party application layer. Some /api/* routes are still externally reachable, but that does not make them stable public contracts.
| Surface | Auth | Audience | Contract |
|---|---|---|---|
| GET /v1 | Anonymous, session, or API key | External integrators and discovery | Public namespace root. Advertises the v1 family. |
| GET /v1/catalog | Anonymous, session, or API key | External integrations, CLI complements, first-party app | Stable public contract. |
| GET /v1/catalog/{id}/similar | Member session or API key with API Origin or Enterprise and catalog:read | Matching workflows, substitution research, and account-linked agents | Beta public contract. Returns cautious candidates, score dimensions, and price deltas, not canonical identity decisions. |
| GET /v1/price-index | API key with Parchment Intelligence access | External integrations and agent workflows consuming market aggregates | Stable aggregate contract backed by price_index_snapshots. No raw supplier rows, CSV export, alerts, or webhooks. |
| GET /api/catalog-api | API key only | Legacy callers only | Deprecated API-key-only alias. Delegates to /v1/catalog with Deprecation and Sunset headers while remaining public-only. Sunset: Dec 31 2026. |
| GET /api/catalog and /api/catalog/filters | Anonymous or session; API key for /api/catalog only | First-party catalog UI | Internal compatibility layer. Do not treat as broad external promise. |
| /api/beans, /api/roast-profiles, /api/profit | Session-authenticated; ownership enforced on writes | Authenticated product users | Internal application routes. |
| /api/chat, /api/workspaces, /api/tools/* | Member session | Paid workspace and AI workflows | Internal product routes. /api/tools/* are deprecated compatibility shims. |
| /api/stripe/* and /api/admin/* | Session, webhook signature, or admin session depending on route | Billing, operations, and support workflows | Internal operational routes. |
Authentication model
- GET /v1/catalog supports anonymous requests for public-only catalog discovery. Anonymous callers get the same public payload shape, but no API-key billing, quota, or X-RateLimit-* usage headers.
- GET /v1/catalog also supports first-party session requests. Viewer sessions stay public-only; member and admin sessions may unlock richer in-app visibility.
- GET /v1/catalog supports API-key requests via Authorization: Bearer <api_key>. API Green stays on the basic public query surface; paid API tiers add structured process facet filtering while remaining public-catalog scoped. API keys use plan-based limits and are the intended production path for server-to-server integrations.
- GET /v1/catalog/{id}/similar requires a member session or an API key with API Origin or Enterprise plus catalog:read. It returns beta similarity candidates for account-linked matching workflows; anonymous callers get 401 and viewer or API Green callers get 403.
- GET /v1/price-index requires an API key whose owner has Parchment Intelligence access. It returns aggregate price-index snapshots, not raw supplier-level rows.
- GET /api/catalog-api is a deprecated legacy alias to /v1/catalog, but it remains API-key-only for backward-compatible machine access.
- Cookies only matter when they resolve to a valid first-party session. A raw Cookie header is not part of the public API contract.
- Inventory share links are the one notable anonymous data exception on the product side: GET /api/beans?share=... can return a scoped inventory view without a user session.
Public catalog request
curl https://purveyors.io/v1/catalog \
-H "Authorization: Bearer pk_live_your_key_here"Choose the right access mode
| Surface | Best for | Auth | Operational contract |
|---|---|---|---|
| Anonymous GET /v1/catalog | Public discovery, quick evaluation, and proof-of-value embeds | None | Public-only data. No X-RateLimit-* headers or API-key usage accounting. |
| API-key GET /v1/catalog | Production integrations, sync jobs, and server-to-server tooling | Authorization: Bearer <api_key> | Public-only data with plan enforcement, X-RateLimit-* headers, and stable HTTP compatibility guarantees. |
| API-key GET /v1/catalog/{id}/similar | Beta similar-coffee matching and substitution research | Authorization: Bearer <api_key> with API Origin or Enterprise plus catalog:read | Plan-limited beta response with target, matches, score dimensions, match category, confidence labels, price_delta_1lb, X-RateLimit-* headers, and cautious copy. |
| API-key GET /v1/price-index | Market-intelligence integrations and agents | Authorization: Bearer <api_key> plus Parchment Intelligence entitlement | Aggregate price_index_snapshots data with pagination and rate-limit headers. No CSV, alerts, webhooks, or supplier-level rows. |
| Session GET /v1/catalog | First-party product reads that share the canonical resource | Valid Purveyors session cookie | Viewer sessions stay public-only. Member and admin sessions may unlock richer in-app visibility. First-party product path only; not the recommended external integration mode. |
| purvey catalog | Terminal workflows, account-linked agents, and stable command automation | Authenticated viewer session | CLI contract with explicit auth prompts and predictable stdout/stderr behavior. Use HTTP instead when anonymous or API-key access is the goal. |
How the product surfaces connect
- /api is the public-facing product page for plans, positioning, and quick start.
- /api-dashboard is the Parchment Console for API keys, usage, subscriptions, and account-aware billing flows.
- /catalog and /analytics are end-user product surfaces that reflect the same coffee domain model as the API.
- /docs is the shared public documentation tree for both the HTTP API and @purveyors/cli.
- /llms.txt, /sitemap.xml, and /blog/feed.xml are anonymous discoverability endpoints for agents, crawlers, and feed readers. They expose navigation metadata, not integration data contracts.
- /auth/callback and /auth/cli-callback are OAuth handoff surfaces. They are part of login flow reliability, not REST API resources.
- The web app imports @purveyors/cli modules directly for chat tooling, so CLI and product behavior should stay aligned.