Internal app routes

Internal app route matrix

Authenticated and internal /api/* routes that power the Purveyors product surface, grouped by capability and stability.

This page distinguishes the stable external v1 contracts, beta catalog endpoints, legacy aliases, internal app APIs, Console control-plane routes, and admin-only surfaces.

Most /api/* routes are not public compatibility promises. Document them accurately, but keep external integrations pointed at /v1/catalog, /v1/catalog/{id}/similar when matching access is available, /v1/price-index for aggregate market data, or @purveyors/cli whenever possible.

Public v1 and legacy route families

Route	Methods	Auth	Stability	Notes
/v1	GET	Anonymous, session, or API key	Namespace descriptor	Advertises the v1 namespace and stable catalog and price-index resources.
/v1/catalog	GET	Anonymous, session, or API key	Stable external contract	Canonical catalog resource for normalized listing reads, proof summaries, plan caps, and API-key rate-limit headers.
/v1/catalog/{id}/similar	GET	Member session or API key with API Origin or Enterprise plus catalog:read	Beta external contract	Catalog similarity candidates with target, grouped canonical candidates vs similar recommendations, score dimensions, identity blocker reasons, price deltas, and cautious beta copy.
/v1/procurement/briefs	GET, POST	Member session or API key with API Origin or Enterprise plus catalog:read	Stable external procurement seed	Creates and lists user-owned saved sourcing criteria. /v1/procurement/briefs/{id} gets one brief, and /v1/procurement/briefs/{id}/matches runs deterministic catalog matches.
/v1/price-index	GET	API key with Parchment Intelligence access	Stable external aggregate contract	Reads aggregate price_index_snapshots only. No raw supplier rows, CSV, alerts, watchlists, or webhooks.
/api/catalog-api	GET	API key only	Deprecated legacy alias	API-key-only alias to /v1/catalog. Always public-only. Sunset: Dec 31 2026.

Catalog and discovery app routes

Route	Methods	Auth	Stability	Notes
/api/catalog	GET	Anonymous, session, or API key	Internal compatibility adapter	Delegates to the canonical catalog resource but can return legacy shapes and adds X-Purveyors-Canonical-Resource: /v1/catalog.
/api/catalog/filters	GET	Anonymous or session	Internal UI helper	Returns stocked-only filter metadata. Privileged sessions can opt into wholesale-aware values.
/api/catalog-api	GET	API key only	Deprecated	Legacy API-key-only alias to /v1/catalog. Always public-only. Sunset: Dec 31 2026.

Inventory and sales routes

Route	Methods	Auth	Stability	Notes
/api/beans	GET POST PUT DELETE	GET: session or share token; writes: session	Internal product route	GET without a valid session returns an empty data array rather than a 401. share=<token> scopes reads to a shared bean or the owner's full inventory.
/api/share	POST	Session	Internal product route	Creates /beans?share=... links for one inventory item or all items.
/api/update-stocked-status	POST PUT	Session	Internal helper	POST recalculates one inventory item by coffee_id. PUT bulk-recomputes the caller's entire inventory.
/api/profit	GET POST PUT DELETE	Session	Internal product route	GET returns both sales and computed profit data. Writes enforce ownership on the underlying sales or inventory rows.

Roast and analysis routes

Route	Methods	Auth	Stability	Notes
/api/roast-profiles	GET POST PUT DELETE	Session	Internal product route	CRUD for roast profiles. POST supports single and batch creation. DELETE accepts id or batch name.
/api/artisan-import	POST	Session	Internal product route	Accepts multipart form-data with file plus roastId. Supported formats: .alog, .alog.json, .json.
/api/roast-chart-data	GET	Session	Internal analysis helper	Requires roastId query param. Returns sampled telemetry and metadata, not raw unbounded sensor streams.
/api/roast-chart-settings	GET	Session	Internal UI helper	Requires roastId query param. Reads saved chart ranges for a roast profile.
/api/clear-roast	DELETE	Session + ownership	Internal maintenance helper	Requires roast_id query param. Clears imported Artisan data and resets related fields.
/api/ai/classify-roast	POST	Session + member role	Internal AI helper	Matches Artisan metadata to inventory candidates. Returns { match } and can emit 429 if the model provider rate-limits.

Chat and workspace routes

Route	Methods	Auth	Stability	Notes
/api/chat	POST	Member session	Internal product route	Streams AI chat responses with workspace context and tool execution.
/api/chat/execute-action	POST	Member session	Internal product route	Executes a constrained set of proposal-card actions: add_bean_to_inventory, update_bean, create_roast_session, update_roast_notes, and record_sale.
/api/workspaces	GET POST	Member session	Internal product route	Lists or creates workspaces. New workspaces default to title "New Workspace" and type "general" when omitted.
/api/workspaces/[id]	GET PUT DELETE	Member session + ownership	Internal product route	GET returns workspace details plus up to 50 messages and updates last_accessed_at.
/api/workspaces/[id]/messages	POST DELETE	Member session + ownership	Internal product route	POST accepts one message or an array and persists parts plus canvas mutations.
/api/workspaces/[id]/canvas	POST PUT	Member session + ownership	Internal product route	Persists canvas_state; POST exists for sendBeacon compatibility.
/api/workspaces/[id]/summarize	POST	Member session + ownership	Internal product route	Compacts recent conversation history into context_summary using the model backend. Returns skipped: true when there are fewer than four saved messages.

Workspace routes are product internals, not agent APIs

These endpoints exist to support the Purveyors chat product. For external automation, prefer the public catalog API or the CLI instead of coupling to chat workspace payloads.

Console and docs-adjacent routes

Outside the JSON route layer, /api/docs and /api-dashboard/docs are legacy docs entry points that 307 redirect to /docs/api/overview.

Treat /docs as the canonical information architecture, /api as the product page, and /api-dashboard as the authenticated Console surface.

Route	Methods	Auth	Stability	Notes
/api-dashboard/keys/generate	POST	Session	Console control-plane route	Creates one API key for the authenticated user and returns the plaintext apiKey only at creation time.
/api-dashboard/keys/deactivate	POST	Session + key ownership	Console control-plane route	Deactivates an owned API key by keyId without exposing the secret again.

Metadata, auth handoff, and crawler routes

These routes are public or browser-reachable support surfaces. They improve agent onboarding, search discovery, feed subscriptions, OAuth reliability, or browser tooling compatibility, but they are not public data APIs.

Route	Methods	Auth	Stability	Notes
/llms.txt	GET	Anonymous	Agent discoverability metadata	Plain-text overview for agents with links to public pages, docs, API contracts, blog posts, and supported workflows.
/sitemap.xml	GET	Anonymous	Crawler metadata	XML sitemap covering public pages, published blog posts, and the docs navigation generated from DOCS_NAV.
/blog/feed.xml	GET	Anonymous	RSS feed	RSS 2.0 feed for published blog posts. It is content syndication, not a catalog or analytics API.
/auth/callback	GET	OAuth code	Auth handoff route	Exchanges a Supabase auth code for a session, sanitizes next to an internal path, and redirects to the target or /auth/auth-code-error.
/auth/cli-callback	GET	OAuth redirect target	CLI login helper page	Browser page that lets remote and headless CLI flows copy the full callback URL back into purvey auth login.
/.well-known/appspecific/com.chrome.devtools.json	GET	Anonymous	Browser tooling compatibility	Returns an empty JSON object for Chrome DevTools app-specific probing. It has no product data contract.

Deprecated tool routes

Route	Methods	Auth	Status	Replacement direction
/api/tools/coffee-catalog	POST	Member session	Deprecated	Prefer direct CLI-library integration or /v1/catalog for external reads.
/api/tools/green-coffee-inv	POST	Member session	Deprecated	Prefer shared inventory modules and CLI flows.
/api/tools/roast-profiles	POST	Member session	Deprecated	Prefer shared roast modules and CLI flows.
/api/tools/bean-tasting	POST	Member session	Deprecated	Prefer shared tasting logic and CLI flows.
/api/tools/coffee-chunks	POST	Member session	Deprecated	Prefer current retrieval modules instead of tool-route coupling.