API reference
API reference
Every Data API endpoint: parameters, request body, responses, examples. Generated from openapi.json.
This reference is generated from importos/apps/api/openapi.json when the documentation is built. If the API spec changes and the reference does not, the generate:check test fails.
Base URL
Production: https://api.importos.app (placeholder domain, the owner confirms the final one). Local: http://127.0.0.1:4114. Interactive Scalar UI is at /docs, the spec itself at /openapi.json.
Endpoints
Catalog
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/catalog/parse-query | Parse a natural-language car search into catalogue filters |
GET | /v1/catalog/search | Search the EU used-car catalogue (natural language and/or filters) |
Contacts
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/contacts | List and search contacts |
POST | /v1/contacts | Create a contact |
GET | /v1/contacts/{id} | Get a contact |
PATCH | /v1/contacts/{id} | Update a contact (partial) |
Deals
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/deals | List deals |
POST | /v1/deals | Create a deal |
GET | /v1/deals/{id} | Get a deal |
POST | /v1/deals/{id}/stage | Move a deal to another stage |
Documents
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/documents/generate | Generate a document for a deal |
Extension
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/extension/exchange | Exchange a Desk one-time code for an API key (Chrome extension sign-in) |
DELETE | /v1/extension/key | Disconnect the extension: revoke the key used for this request |
POST | /v1/extension/lot | Add a lot to Desk: vehicle + offer for a client request |
GET | /v1/extension/me | Who this key belongs to and what it may do |
GET | /v1/extension/requests | Open client requests to attach a lot to |
Leads
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/leads | Register a lead |
Shipments
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/shipments | Shipments of a deal |
POST | /v1/shipments | Attach or update the shipment of a deal |
POST | /v1/shipments/{id}/refresh | Poll the tracker now |
Underwriter
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/underwrite | AI underwriter: repair estimate, risk flags, resale forecast and maximum bid for a lot |
Webhooks
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/webhooks | List webhook subscriptions |
POST | /v1/webhooks | Subscribe a URL to events |
PATCH | /v1/webhooks/{id} | Change or re-enable a subscription |
DELETE | /v1/webhooks/{id} | Delete a subscription |
GET | /v1/webhooks/{id}/deliveries | Delivery log of a subscription |
POST | /v1/webhooks/{id}/rotate-secret | Issue a new signing secret |
Pricing
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/fx | Exchange rate |
POST | /v1/landed-cost | Landed cost of a car imported from a US/EU auction |
GET | /v1/market-price | Market price estimate (p25 / median / p75) from listings |
GET | /v1/rules/{country} | Customs and registration rules in force |
GET | /v1/tariffs | Tariffs used for the tenant |
Listings and VIN
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/catalog/similar | Similar cars in the EU catalog (count and median price) |
GET | /v1/listings/search | Normalized search across listing sources |
GET | /v1/vin/{vin} | Decode a VIN and list known lots/listings |
MCP
| Method | Endpoint | Description |
|---|---|---|
POST | /mcp | MCP endpoint (streamable HTTP, JSON-RPC 2.0) |
System
Errors
All errors are application/problem+json (RFC 9457) with a stable code and a request_id. Details and the code table are in Authentication and limits.