API Reference

This reference lists routes found in the NestJS controllers and Next.js route handlers. It does not infer payloads, responses, error codes, or hosted availability beyond what the source implements.

Base URLs

Environment	API	Web
Production	`https://api.dealeros.pndsvcs.com`	`https://app.dealeros.pndsvcs.com`
Local	`http://localhost:4000`	`http://localhost:3000`

Authentication

The Nest API is default-deny. Unless a route is explicitly public, send both headers:

Authorization: Bearer <auth0-access-token>
x-dealeros-tenant-id: <tenant-uuid>

The tenant UUID must identify an active tenant associated with the token’s Auth0 organization, and the subject must have an active membership. Public webhooks do not use bearer authentication; their handlers verify the provider-specific signature. The signup and public lead routes apply their own abuse controls.

Request examples

curl -fsS http://localhost:4000/health

curl -fsS http://localhost:4000/v1/inventory \
  -H 'Authorization: Bearer <auth0-access-token>' \
  -H 'x-dealeros-tenant-id: <tenant-uuid>'

Access	Method	Path	Purpose
Public	`GET`	`/health`	Check API and database readiness
Protected	`GET`	`/v1/session/me`	Return the verified subject and resolved tenant context
Public	`POST`	`/v1/session/login-sync`	Verify an Auth0 ID token and synchronize an existing identity
Public	`POST`	`/v1/session/org-discovery`	Verify an Auth0 ID token and find available organizations
Public	`POST`	`/v1/signup/provision`	Provision a self-service tenant after Turnstile and rate-limit checks
Public	`GET`	`/v1/billing/plans`	List plan tiers used by the pricing surface
Protected	`GET`	`/v1/billing/summary`	Return the tenant billing summary
Protected	`POST`	`/v1/billing/trial`	Start the selected plan’s trial
Protected	`POST`	`/v1/billing/checkout`	Create a Stripe Checkout session
Protected	`POST`	`/v1/billing/portal`	Create a Stripe billing-portal session
Signed webhook	`POST`	`/webhooks/stripe`	Verify and process a Stripe event

Organization, onboarding, and invitations

Access	Method	Path	Purpose
Protected	`GET`	`/v1/organization/summary`	Return tenant, rooftop, and membership data
Protected	`GET`	`/v1/onboarding`	Return onboarding progress
Protected	`POST`	`/v1/onboarding/steps`	Save, complete, or skip an onboarding step
Protected	`POST`	`/v1/onboarding/rooftops`	Create a rooftop
Protected	`GET`	`/v1/invitations`	List pending invitations
Protected	`POST`	`/v1/invitations`	Create a tenant invitation
Protected	`POST`	`/v1/invitations/:id/resend`	Resend an invitation
Protected	`DELETE`	`/v1/invitations/:id`	Revoke an invitation
Public	`POST`	`/v1/invitations/accept`	Verify an ID token and invitation ticket, then accept the invite

Inventory and media

Access	Method	Path	Purpose
Protected	`GET`	`/v1/inventory`	List tenant inventory
Protected	`POST`	`/v1/inventory`	Create an inventory unit
Protected	`GET`	`/v1/inventory/:id`	Return one inventory unit
Protected	`PATCH`	`/v1/inventory/:id`	Update status, custody location, price, or currency
Protected	`GET`	`/v1/inventory/:inventoryUnitId/media`	List attached media
Protected	`POST`	`/v1/inventory/:inventoryUnitId/media`	Attach a validated media object
Protected	`DELETE`	`/v1/media/:mediaAssetId`	Remove a media asset
Public	`GET`	`/v1/public/media/:mediaAssetId`	Deliver media belonging to a published listing

Marketplace

Access	Method	Path	Purpose
Protected	`GET`	`/v1/marketplace/settings`	Return dealer marketplace settings
Protected	`PUT`	`/v1/marketplace/settings`	Create or update marketplace settings
Protected	`GET`	`/v1/marketplace/offers`	List tenant offers
Protected	`GET`	`/v1/inventory/:inventoryUnitId/offer`	Return the offer for an inventory unit
Protected	`PUT`	`/v1/inventory/:inventoryUnitId/offer`	Create or update an inventory offer
Protected	`POST`	`/v1/marketplace/offers/:offerId/publish`	Publish an offer
Protected	`POST`	`/v1/marketplace/offers/:offerId/unpublish`	Unpublish an offer
Protected	`POST`	`/v1/marketplace/offers/:offerId/suppress-sold`	Suppress a sold offer
Protected	`GET`	`/v1/marketplace/listings/search`	Search published listings within tenant context
Protected	`GET`	`/v1/marketplace/saved-searches`	List the current actor’s saved searches
Protected	`POST`	`/v1/marketplace/saved-searches`	Create a saved search
Protected	`DELETE`	`/v1/marketplace/saved-searches/:savedSearchId`	Delete a saved search
Protected	`GET`	`/v1/marketplace/favorites`	List the current actor’s favorites
Protected	`POST`	`/v1/marketplace/favorites`	Add a listing to favorites
Protected	`DELETE`	`/v1/marketplace/favorites/:listingId`	Remove a listing from favorites
Public	`GET`	`/v1/public/marketplace/listings`	Search public listings
Public	`GET`	`/v1/public/marketplace/listings/:slug`	Return one public listing

The implemented search query accepts text, make, model, year range, price range, maximum mileage, sort, page, and page size. The default backend is PostgreSQL. The Azure AI Search adapter is present but unavailable in this milestone.

Leads

Access	Method	Path	Purpose
Public	`POST`	`/v1/public/marketplace/listings/:slug/leads`	Capture a consented inquiry for a public listing
Protected	`GET`	`/v1/leads`	List tenant leads
Protected	`PATCH`	`/v1/leads/:leadId`	Update lead status, assignment, or note
Protected	`GET`	`/v1/leads/routing-rules`	List routing rules
Protected	`POST`	`/v1/leads/routing-rules`	Create a routing rule
Protected	`DELETE`	`/v1/leads/routing-rules/:routingRuleId`	Delete a routing rule

Providers and inbound webhooks

Access	Method	Path	Purpose
Protected	`GET`	`/v1/providers`	Return provider catalog, entitlements, routes, health, and recent usage
Protected	`PUT`	`/v1/providers/entitlements`	Enable or disable a provider entitlement
Protected	`PUT`	`/v1/providers/routes`	Set provider fallback order for a category
Protected	`POST`	`/v1/providers/vin-decode`	Dispatch VIN decoding through the provider framework
Protected admin	`POST`	`/v1/providers/lifecycle/test-event`	Send a lifecycle test event for the authenticated actor
Signed webhook	`POST`	`/webhooks/providers/:providerKey`	Verify and store a provider webhook
Signed webhook	`POST`	`/webhooks/resend`	Verify and store a Resend webhook

Next.js route handlers

These handlers belong to the web application, not the Nest API:

Method	Path	Purpose
`GET`	`/api/auth/login`	Begin Auth0 login
`GET`	`/api/auth/callback`	Finish Auth0 login and establish the server-side session
`GET`	`/api/auth/logout`	Clear the session and begin Auth0 logout
`GET`	`/api/auth/me`	Return the current web-session state
`GET`	`/api/auth/signup`	Begin the plan-aware signup flow
`GET`	`/invite/accept`	Begin invitation acceptance
`GET`	`/login`	Redirect to the login handler
`GET`	`/health`	Return web-service liveness
`POST`	`/api/public/leads`	Validate and forward the marketing contact form when delivery is configured

Start here

Documentation hubs

Legal

Shared legal

API Reference

API Reference

Base URLs

Authentication

Request examples

Organization, onboarding, and invitations

Inventory and media

Marketplace

Leads

Providers and inbound webhooks

Next.js route handlers

​API Reference

​Base URLs

​Authentication

​Request examples

​Session, signup, health, and billing

​Organization, onboarding, and invitations

​Inventory and media

​Marketplace

​Leads

​Providers and inbound webhooks

​Next.js route handlers

API Reference

Base URLs

Authentication

Request examples

Session, signup, health, and billing

Organization, onboarding, and invitations

Inventory and media

Marketplace

Leads

Providers and inbound webhooks

Next.js route handlers