Back to home

Public REST API

CarModPlanner exposes a read-mostly REST API powering the public catalog and the build planner. The same API is consumed internally by the site, so anything you see in the UI is reachable programmatically.

OpenAPI 3.0.3 SpecAPI Catalog (RFC 9727)Agent Skills Index

Authentication

Every endpoint listed below is currently unauthenticated. OAuth 2.0 / OIDC discovery documents are published at /.well-known/oauth-authorization-server and /.well-known/openid-configuration as stubs (each carries X-Stub: true and "_status": "planned" in the body). When user accounts and write-scoped APIs ship, those documents will go live and the relevant endpoints below will require a Bearer token with the appropriate scope.

For AI agents

Pages on this site also support Accept: text/markdown content negotiation — append --header "Accept: text/markdown" to any curl call to get a markdown summary of a part / blog post / category page instead of HTML. In-browser agents can drive the build planner via 12 WebMCP tools surfaced through navigator.modelContext.provideContext() (mounted on every page). See the agent skills index for capability descriptions.

Endpoints

Catalog

GET/api/categories

List every part category with its subcategories and part counts.

curl https://carmodplanner.com/api/categories
GET/api/parts

Search the parts catalog. Supports `search`, `category`, `subcategory`, `brand`, `ids`, `limit`.

curl "https://carmodplanner.com/api/parts?search=cold+air+intake&limit=5"
GET/api/price-history

Return price history + current retailer prices + min/max stats for a part.

curl "https://carmodplanner.com/api/price-history?partId=302&days=90"

Builds

POST/api/builds

Create a public build (rate-limited).

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"Stage 1 Scat Pack","trim":"scatpack-6-4","partIds":[302,318]}' \
  https://carmodplanner.com/api/builds
POST/api/build-check

Run the canonical v2 compatibility evaluator. Returns blocks, warnings, recommendations.

curl -X POST -H "Content-Type: application/json" \
  -d '{"partIds":[302,318,416],"variantSlug":"scatpack-6-4"}' \
  https://carmodplanner.com/api/build-check

Canonical

GET/api/canonical/products

List canonical products. Filterable by `ids`, `legacyIds`, `componentSlug`, `variantSlug`.

curl "https://carmodplanner.com/api/canonical/products?legacyIds=302,318"
GET/api/canonical/systems

Full systems > subsystems > components hierarchy used by the build planner UI.

curl https://carmodplanner.com/api/canonical/systems
POST/api/canonical/evaluate

Evaluator that accepts CanonicalProduct IDs directly (vs /api/build-check which takes legacy Part IDs).

curl -X POST -H "Content-Type: application/json" \
  -d '{"productIds":[42,73],"variantSlug":"scatpack-6-4"}' \
  https://carmodplanner.com/api/canonical/evaluate

Ops

GET/api/health

Health probe used by load balancers and the API catalog's `status` link.

curl https://carmodplanner.com/api/health
GET/api/og/build

Open Graph image for shareable build URLs (1200x630 PNG).

curl -o build.png "https://carmodplanner.com/api/og/build?parts=302,318&name=Stage+1"

Rate limits + caching

Questions?

Email hello@carmodplanner.com. API breaking changes ship with a deprecation header and a 90-day sunset window.