> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> DealerOS backend endpoints, web handlers, authentication boundary, and request examples grounded in source code.

# 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:

```http theme={null}
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

```bash theme={null}
curl -fsS http://localhost:4000/health
```

```bash theme={null}
curl -fsS http://localhost:4000/v1/inventory \
  -H 'Authorization: Bearer <auth0-access-token>' \
  -H 'x-dealeros-tenant-id: <tenant-uuid>'
```

## Session, signup, health, and billing

| 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.