API v1
REST API used by the website itself. JSON responses { ok, message, ... } or errors { error, code, fields } with proper HTTP codes (400 validation, 401, 403 RBAC, 404, 409 business rule, 422, 429 rate limit). Mutations require the X-CSRF-Token header (value of the ap_csrf cookie). OpenAPI spec: /openapi.json.
Real-time: Socket.IO at /socket.io · client events join {lotId|eventId}, sync, bid {lotId, amountCents, idempotencyKey} · server events lot:update, lot:closed, event:update, notification.
Auth & account
| Method | Path | Description | Access |
|---|
| POST | /api/v1/auth/register | Create account (step 1) | public |
| POST | /api/v1/auth/login | Sign in (buyer/seller mode) | public |
| POST | /api/v1/auth/logout | Sign out | user |
| GET | /api/v1/auth/me | Current user | public |
| POST | /api/v1/auth/forgot-password | Request reset link | public |
| POST | /api/v1/auth/reset-password | Reset password with token | public |
| POST | /api/v1/auth/change-password | Change password | user |
| POST | /api/v1/memberships/choose | Choose membership (creates invoice if paid) | buyer |
| POST | /api/v1/documents | Upload verification document (multipart) | user |
| PATCH | /api/v1/profile | Update profile | user |
Catalog & search
| Method | Path | Description | Access |
|---|
| GET | /api/v1/makes | Makes with models | public |
| GET | /api/v1/makes/:id/models | Models of a make | public |
| GET | /api/v1/vehicle-types | Vehicle types | public |
| GET | /api/v1/damage-types | Damage types | public |
| GET | /api/v1/locations | Yards | public |
| GET | /api/v1/lots?q&make&model&type&condition&year_from&year_to&odo_min&odo_max&location&damage&status&sort&page&per_page | Paginated lot search | public |
| GET | /api/v1/lots/:lotNumber | Lot detail + bid history | public |
| GET | /api/v1/auctions | Auction events | public |
| GET | /api/v1/fees/estimate?amount= | Cost calculator | public |
Bidding (also via WebSocket event "bid")
| Method | Path | Description | Access |
|---|
| POST | /api/v1/lots/:id/bids | Pre-bid / live bid. Body {amount, idempotency_key} | bids.place |
| POST | /api/v1/watchlist/:lotId | Toggle watchlist | user |
| POST | /api/v1/saved-searches | Save search | user |
| DELETE | /api/v1/saved-searches/:id | Delete saved search | user |
Alerts & support
| Method | Path | Description | Access |
|---|
| POST | /api/v1/alerts | Create vehicle alert | public |
| PATCH | /api/v1/alerts/:token | Edit alert | token |
| POST | /api/v1/alerts/:token/cancel | Cancel alert | token |
| POST | /api/v1/support/tickets | Contact form | public |
Orders, payments, transport, pickup
| Method | Path | Description | Access |
|---|
| POST | /api/v1/invoices/:id/payments/demo | Demo payment (bank transfer + receipt, or sandbox card) | owner |
| POST | /api/v1/payments/:id/review | Approve/reject payment | finance.review |
| POST | /api/v1/orders/:id/cancel | Cancel unpaid order | finance.review |
| POST | /api/v1/transport/estimate | Public transport estimate | public |
| POST | /api/v1/orders/:id/transport-quotes | Quote for a purchase | owner |
| POST | /api/v1/transport/quotes/:id/accept | Accept quote → transport order + invoice | owner |
| POST | /api/v1/transport-orders/:id | Update transport status | logistics.manage |
| POST | /api/v1/pickup-passes/validate | Validate pickup PIN | pickup.validate |
Seller
| Method | Path | Description | Access |
|---|
| POST | /api/v1/seller/apply | Apply as seller | user |
| POST | /api/v1/seller/vehicles | Create draft | vehicles.sell |
| PATCH | /api/v1/seller/vehicles/:id | Edit draft | vehicles.sell |
| DELETE | /api/v1/seller/vehicles/:id | Delete draft | vehicles.sell |
| POST | /api/v1/seller/vehicles/:id/submit | Submit for approval | vehicles.sell |
| POST | /api/v1/seller/vehicles/:id/images | Upload photos (multipart) | vehicles.sell |
| POST | /api/v1/seller/vehicles/:id/documents | Upload document | vehicles.sell |
| POST | /api/v1/seller/lots/:id/decision | Accept/reject bid below reserve | vehicles.sell |
Administration
| Method | Path | Description | Access |
|---|
| PATCH | /api/v1/admin/users/:id | Status, roles, plan, verification | users.manage |
| POST | /api/v1/admin/users | Create user | users.manage |
| POST | /api/v1/admin/documents/:id/review | Approve/reject document | documents.review |
| POST | /api/v1/admin/sellers/:id/approve | Approve seller | users.manage |
| POST | /api/v1/admin/vehicles/:id/review | Approve (assign to auction) / reject | vehicles.approve |
| POST | /api/v1/admin/events | Schedule auction | auctions.manage |
| POST | /api/v1/admin/events/:id/start | Start auction now | auctions.manage |
| POST | /api/v1/admin/events/:id/cancel | Cancel auction | auctions.manage |
| PATCH | /api/v1/admin/lots/:id | Edit lot prices | auctions.manage |
| PATCH | /api/v1/admin/plans/:id | Edit membership limits | settings.manage |
| PATCH | /api/v1/admin/settings/:key | Edit setting | settings.manage |
| POST | /api/v1/admin/catalog/:kind | Create make/model/type/damage | catalog.manage |
| POST | /api/v1/admin/locations | Create yard | locations.manage |
| PATCH | /api/v1/admin/pages/:slug | Edit content page | content.manage |
| GET | /api/v1/reports/:name.csv | Export CSV report | reports.view |