# plan.parts

> Auto parts data relay API platform. Access aftermarket parts data (aftermarket catalog), PowerCatalog (sports equipment) and other automotive databases via REST API. Pay per request — tokens deducted only on successful responses.

## About

plan.parts is a B2B API relay platform that provides structured access to multiple automotive parts databases through a unified REST interface. The platform acts as a transmitter — data is sourced from third-party providers and their original databases; plan.parts does not own or license the underlying data. Customers pay per successful API request using a token system. This makes it cost-effective for developers, businesses, and AI agents that need automotive data without hosting their own databases.

## Authentication

All API endpoints require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are generated in the Developer Portal at https://plan.parts/portal/api-keys

## Token Billing

- Tokens are deducted only on successful (2xx) responses
- HTTP 402 is returned when token balance is insufficient
- Free tier: bonus tokens provided to all new accounts, no credit card required
- Token costs are fixed per endpoint (see endpoint list below)

## Base URL

```
https://plan.parts/api
```

## API Endpoints

### Aftermarket (OEM / OE / IAM)

- `GET /api/v1/aftermarket/health` — Aftermarket API availability check [free]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/aftermarket-health
- `GET /api/v1/aftermarket/articles/{art_id}/criteria` — Technical specifications and fitment criteria for an article [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/article-criteria
- `GET /api/v1/aftermarket/articles/{art_id}/media` — Images and documents for an article [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/article-media
- `GET /api/v1/aftermarket/catalog/brands` — List of all vehicle manufacturers (708 brands) [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/catalog-brands
- `GET /api/v1/aftermarket/catalog/categories` — List of parts categories for a vehicle (K-Type) [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/catalog-categories
- `GET /api/v1/aftermarket/catalog/models` — List of model series for a manufacturer [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/catalog-models
- `GET /api/v1/aftermarket/catalog/modifications` — List of vehicle modifications for a model series [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/catalog-modifications
- `GET /api/v1/aftermarket/search/suggest` — Autocomplete suggestions for article search queries [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/search-suggest
- `GET /api/v1/aftermarket/ktype` — Search vehicles by brand, model, engine, year or K-Type [1 token]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/vehicle-search-k-type
- `GET /api/v1/aftermarket/articles/{art_id}/crosses` — OEM and cross-reference numbers for an article [2 tokens]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/article-crosses
- `GET /api/v1/aftermarket/articles/{art_id}` — Full article details: name, brand, attributes, images, OEM numbers [2 tokens]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/article-detail
- `GET /api/v1/aftermarket/articles/{art_id}/vehicles` — Compatible vehicles (fitments/linkages) for an aftermarket article [2 tokens]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/article-vehicles
- `GET /api/v1/aftermarket/catalog/articles` — List of spare part articles for a vehicle and category [2 tokens]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/catalog-articles
- `GET /api/v1/aftermarket/search` — Search parts by article number, OEM, EAN or IAM [2 tokens]
  Docs: https://plan.parts/docs/aftermarket-oem-oe-iam/search-articles

### PowerCatalog

- `GET /api/v1/pc/groups` — List of all equipment groups [free]
  Docs: https://plan.parts/docs/powercatalog/equipment-groups
- `GET /api/v1/pc/bodies` — List of assemblies for a model [1 token]
  Docs: https://plan.parts/docs/powercatalog/assemblies-for-model
- `GET /api/v1/pc/brands` — List of brands by equipment group [1 token]
  Docs: https://plan.parts/docs/powercatalog/brands-for-group
- `GET /api/v1/pc/models` — List of models by production year [1 token]
  Docs: https://plan.parts/docs/powercatalog/models-for-year
- `GET /api/v1/pc/years` — List of production years by brand [1 token]
  Docs: https://plan.parts/docs/powercatalog/years-for-brand
- `GET /api/v1/pc/parts` — List of spare parts with articles and images [2 tokens]
  Docs: https://plan.parts/docs/powercatalog/parts-for-assembly

### System

- `GET /api/v1/ping` — Connection and authentication check [free]
  Docs: https://plan.parts/docs/system/ping

### VAG Catalog (ETKA)

- `GET /api/v1/vag/catalogs` — List of available VAG catalogs (VW, Audi, Skoda, SEAT, Porsche) [free]
  Docs: https://plan.parts/docs/vag-catalog-etka/vag-catalogs
- `GET /api/v1/vag/health` — VAG ETKA API availability check [free]
  Docs: https://plan.parts/docs/vag-catalog-etka/vag-health
- `GET /api/v1/vag/part/{number}/images` — Images for an OEM part [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-images
- `GET /api/v1/vag/part/{number}` — OEM part details: name, status, synonyms, replacements [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-info
- `GET /api/v1/vag/part/{number}/price` — Official OEM price for a part [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-price
- `GET /api/v1/vag/part/{number}/supersessions` — Successor and predecessor part numbers [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-supersessions
- `GET /api/v1/vag/part/{number}/vehicles` — List of vehicles that use a specific OEM part [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-vehicles
- `GET /api/v1/vag/vehicles` — Search vehicles by catalog, model, year or text query [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/search-vehicles
- `GET /api/v1/vag/vehicle/{epis_typ}/groups` — List of part groups for a vehicle [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/vehicle-groups
- `GET /api/v1/vag/vehicle/{epis_typ}/subgroups` — List of part subgroups for a vehicle group [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/vehicle-subgroups
- `GET /api/v1/vag/vin/{vin}` — Decode VIN to vehicle specification [1 token]
  Docs: https://plan.parts/docs/vag-catalog-etka/vin-lookup
- `GET /api/v1/vag/part/{number}/cross` — Cross-reference numbers for an OEM part [2 tokens]
  Docs: https://plan.parts/docs/vag-catalog-etka/part-cross-references
- `GET /api/v1/vag/vehicle/{epis_typ}/parts` — List of OEM parts for a vehicle subgroup [2 tokens]
  Docs: https://plan.parts/docs/vag-catalog-etka/vehicle-parts

## Data Tasks (Managed Data Services)

In addition to the self-serve REST API, plan.parts offers **Data Tasks** — one-time managed data jobs executed by the plan.parts team. Use tasks when:
- You need a large slice of data (e.g. all parts for a brand with weights) without maintaining a database license
- You want to enrich an existing catalog (cross-references, vehicle fitment, OEM mapping)
- Integration via API is impractical and a delivered file (CSV, Excel) is sufficient

### How Data Tasks Work

1. **Submit** — POST to the portal or visit https://plan.parts/portal/tasks/create. Provide title, category, description, optional input files (CSV/Excel/ZIP up to 100 MB each), and optional server/DB credentials.
2. **Estimate** — The team reviews and sets a token cost. You receive a notification.
3. **Approve** — Confirm the estimate; tokens are reserved from your balance. Or set "start_immediately" at submission to skip this step.
4. **Receive** — Result files and delivery notes appear in the task thread. Download and import.

### Task Categories

- `data_enrichment` — Add missing attributes (weights, dimensions, EAN) to existing parts
- `cross_reference` — Build cross-number tables from OEM/OE/aftermarket databases
- `vehicle_fitment` — Map articles to make/model/year applicability
- `file_analysis` — Parse and analyse uploaded price lists or catalog files
- `db_analysis` — Query or export data from a connected database
- `custom` — Any other automotive data task

### Task Pricing

- Simple tasks (brand/model lookups, small tables): 100–500 tokens
- Medium tasks (fitment enrichment, price analysis): 500–5,000 tokens
- Complex tasks (full catalog cross-referencing, large DB analysis): 5,000+ tokens
- Tokens are charged only after task completion and client approval
- Example: collect all FEBI brand parts with weights → 824 tokens ≈ $0.66

### Task API (Portal)

- Submit task: https://plan.parts/portal/tasks/create
- View tasks: https://plan.parts/portal/tasks
- Task detail page: https://plan.parts/portal/tasks/{id}
- Data Tasks overview: https://plan.parts/services

## Resources

- OpenAPI 3.0 schema: https://plan.parts/openapi.json
- Documentation: https://plan.parts/docs
- Developer Portal: https://plan.parts/portal
- Data Tasks (managed services): https://plan.parts/services
- Register: https://plan.parts/register
- GitHub examples: https://github.com/plan-parts
- Support: plandevp@gmail.com

## Use Cases

- Look up spare parts for a vehicle by brand/model/year
- Search parts by article number (OEM, EAN, IAM)
- Get vehicle K-Type identifier for aftermarket catalog traversal
- Browse parts categories and assemblies for a specific vehicle
- Retrieve part images and cross-references
- Order a one-time data enrichment task (cross-references, fitment, price analysis) without a database license