Parchment Platform
API overview
Parchment Platform ships one stable public catalog API and a larger internal platform route layer for the web app.
Parchment is the API and Console layer inside Purveyors. It exposes normalized green coffee catalog data through a small public HTTP contract and a broader authenticated product backend. Those surfaces share domain logic, but they do not carry the same compatibility promises.
The stable public contract is GET /v1/catalog. 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 platform 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 /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.
- 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-key requests stay public-only, use plan-based limits, and are the only catalog requests that receive X-RateLimit-* headers.
- 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.
curl https://purveyors.io/v1/catalog \
-H "Authorization: Bearer pk_live_your_key_here"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.
- The web app imports @purveyors/cli modules directly for chat tooling, so CLI and product behavior should stay aligned.