# Navi API Contract Registry

Audit date: 2026-05-05
Current API prefix: `/v1`
Prompt-compatible `/api` aliases are not currently implemented.

Live repo evidence checked for this registry:

- API modules present under `apps/api/src/modules`: auth, users, geo, destinations, listings, bookings, saved, payments, refunds, payouts, businesses, memberships, roles, permissions, audit, content, emergency, trip-planner, translator, webhooks, dashboard, health, i18n.
- API modules missing for Phase One transactional completeness: profiles, providers namespace, categories endpoint, global search, home aggregate, banners, marketing page reads, orders, taxi, food, pharmacy, grocery, SIM, support, uploads, notifications, super admin write/settings surface.
- Database models present in `apps/api/prisma/schema.prisma` include `User`, `Business`, `Listing`, `Room`, `EmergencyNumber`, `Booking`, `Order`, `PaymentIntent`, `SavedItem`, `Trip`, `SupportTicket`, `AuditLog`, `ContentAsset`, `MarketingPage`, `OnboardingPage`, and `TranslationJob`.
- Database models still missing or only represented indirectly include `Profile`, `ProviderTeamMember`, dedicated `Hotel`, `Experience`, `Restaurant`, `MenuItem`, `Product`, `SIMPlan`, `OrderItem`, `PaymentTransaction`, `TripPlan`, `EmergencyContact`, `UploadFile`, `Banner`, `Notification`, `PrescriptionRequest`, and driver assignment.

Status meanings:

- Exists: implemented and route is present.
- Partial: related endpoint exists but does not fully match requested behavior.
- Missing: not implemented.
- Broken: implemented but known to be unsafe or not production-ready.

| Feature | Method | Endpoint | Purpose | Request body | Response body | Required role | Required permission | Database models used | Mobile screens using it | Dashboard screens using it | Status | Fix required |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Auth | POST | `/v1/auth/signup` | Register user and create signup OTP | fullName, email, phoneE164, password, locale, acceptTerms | userId, optional devCode | Guest | Public | User, UserCredential, OtpCode, Role/UserRole | Signup | None | Exists | Add `/register` alias if required |
| Auth | POST | `/v1/auth/login` | Password login | email, password | accessToken, refreshToken, expiresAt, userId | Guest | Public | User, UserCredential, Session | Login, Dashboard login | Dashboard login | Exists | Add device/platform capture |
| Auth | POST | `/v1/auth/refresh` | Rotate refresh token | refreshToken | accessToken, refreshToken, expiresAt | User | Public with refresh token | Session | API client | Dashboard session path indirect | Exists | Add mobile tests |
| Auth | POST | `/v1/auth/logout` | Revoke session | refreshToken/sessionId | ok | User | `profile.read.own` | Session, AuditLog | Profile logout | Dashboard logout | Missing | Add endpoint and call it before local clear |
| Auth | GET | `/v1/auth/me` | Current user/access | none | user/access | User | `profile.read.own` | User, Role, Permission | Session restore | Dashboard | Missing | Add alias to `/users/me` and `/users/me/access` |
| Auth social | POST | `/v1/auth/social/google` | Google login/signup | provider token, device | tokens/user | Guest | Public | User, UserCredential, Session | Login/Signup | Optional | Missing | Add provider abstraction or hide buttons |
| Auth social | POST | `/v1/auth/social/apple` | Apple login/signup | identity token, device | tokens/user | Guest | Public | User, UserCredential, Session | Login/Signup | Optional | Missing | Add provider abstraction or hide buttons |
| Auth OTP | POST | `/v1/auth/otp/request` | Request OTP | email, purpose | ok, optional devCode | Guest | Public | User, OtpCode | OTP resend | None | Exists | Add resend throttling UI/timer |
| Auth OTP | POST | `/v1/auth/otp/verify` | Verify OTP | email, purpose, code | ok or tokens | Guest | Public | User, OtpCode, Session | OTP | None | Exists | Add phone verification later |
| Auth reset | POST | `/v1/auth/forgot-password` | Start reset | email | ok, optional devCode | Guest | Public | User, OtpCode | Forgot Password | None | Exists | None |
| Auth reset | POST | `/v1/auth/reset-password` | Set password after OTP | email, code, password | ok | Guest | Public | UserCredential, OtpCode, Session | Reset Password | None | Exists | Add confirm password client validation |
| User | GET | `/v1/users/me` | Current profile basics | none | User | Tourist/Premium/etc. | `profile.read.own` | User | Login session fetch, profile | Settings | Exists | Add PATCH |
| User access | GET | `/v1/users/me/access` | Current roles/permissions/memberships | none | CurrentAccess | Dashboard user | `profile.read.own` | User, Role, Permission, UserMembership | API client | All dashboard pages | Exists | None |
| User | PATCH | `/v1/users/me` | Update own profile | profile fields | User | Tourist | `profile.update.own` | User/Profile | Profile/Edit | None | Missing | Add Profile model and endpoint |
| User sessions | GET | `/v1/users/me/sessions` | List devices/sessions | none | Session[] | Tourist | `profile.read.own` | Session | Settings/Security | None | Missing | Add device sessions API |
| User sessions | DELETE | `/v1/users/me/sessions/:id` | Revoke device | none | ok | Tourist | `profile.update.own` | Session | Settings/Security | None | Missing | Add endpoint |
| User delete | DELETE | `/v1/users/me` | Delete own account | confirmation | ok | Tourist | `profile.update.own` | User, AuditLog | Settings/Security | Admin users | Missing | Add soft delete policy |
| Profile | GET/PATCH | `/v1/profile` | Rich profile/preferences | profile fields | Profile | Tourist | `profile.read.own`/`profile.update.own` | Profile | Profile/Edit | Users detail | Missing | Add model/API |
| Home | GET | `/v1/home` | Aggregate home hero/services/banners/featured | query locale | home payload | Guest | Public | Banner, Listing, Destination, Category | Home | Content/Banners | Missing | Add aggregate endpoint and CMS |
| Onboarding | GET | `/v1/onboarding` | Onboarding CMS pages | locale | pages | Guest | Public | OnboardingPage | Onboarding | Onboarding Content | Partial | Model added; add API/dashboard |
| Banners | GET | `/v1/banners` | Active home/offers banners | placement, locale | Banner[] | Guest | Public | Banner | Home | Banners | Missing | Add model/API/dashboard |
| Marketing pages | GET | `/v1/marketing/pages` | CMS marketing pages | locale | pages | Guest | Public | MarketingPage | Website | Marketing Pages | Partial | Model added; add API/dashboard |
| Marketing page | GET | `/v1/marketing/pages/:slug` | CMS page by slug | none | MarketingPage | Guest | Public | MarketingPage | Website | Marketing Pages | Partial | Model added; add API/dashboard |
| Discovery | GET | `/v1/emirates` | UAE city/emirate list | none | EmirateCity[] | Guest | Public | City, Region | Home, Trip Step 1 | Settings/countries later | Exists | Add admin countries/emirates editor |
| Discovery | GET | `/v1/categories` | Categories | filters | Category[] | Guest | Public | Category | Discover/Services | Content/Listings | Missing | Add endpoint |
| Discovery | GET | `/v1/destinations` | Featured destinations | none | Destination[] | Guest | Public | Destination | Home, Discover, Saved | Content | Exists | Add filters/detail by id |
| Discovery | GET | `/v1/destinations/:slug` | Destination detail | none | Destination | Guest | Public | Destination | Missing destination detail | Content | Exists by slug | Add mobile route |
| Listings | GET | `/v1/listings` | Published listings | kind, cityId | Listing[] | Guest | Public | Listing | Home, Discover, Services, Bookings lookup | Listings | Exists | Add pagination/search/filter |
| Listings | GET | `/v1/listings/:id` | Listing with rooms | none | Listing & rooms | Guest | Public | Listing, Room | Listing Detail | Listings | Exists | Add amenities/reviews/map |
| Search | GET | `/v1/search` | Global search | q, filters | results | Guest | Public | Listing, Destination, Category | Discover | Dashboard content maybe | Missing | Add endpoint |
| Saved | GET | `/v1/saved` | Saved items | none | SavedItem[] | Tourist | `saved.read.own` | SavedItem | Saved, Discover | None | Exists | Include populated refs later |
| Saved | POST | `/v1/saved` | Save item | refType, refId | SavedItem | Tourist | `saved.create.own` | SavedItem | Discover, Listing, Itinerary | None | Exists | Add validation ref exists |
| Saved | DELETE | `/v1/saved/:refType/:refId` | Unsave item | none | void | Tourist | `saved.delete.own` | SavedItem | Discover/Listing | None | Exists | Make idempotent |
| Booking | POST | `/v1/bookings` | Create booking | listingId, kind, dates, guests | Booking | Tourist | `booking.create` | Booking, Listing | Listing Detail | Bookings | Exists | Add quote/payment/room selection |
| Booking | GET | `/v1/bookings/mine` | Own bookings | none | Booking[] | Tourist | `booking.read.own` | Booking | Bookings | None | Exists | None |
| Booking | GET | `/v1/bookings/:id` | Own booking detail | id | Booking | Tourist | `booking.read.own` | Booking | Missing detail | Dashboard Bookings | Exists for own | Add dashboard/detail route |
| Booking admin | GET | `/v1/bookings` | Admin/provider bookings | none | Booking[] | Provider/Admin | `booking.read.all`/`booking.read.assigned` | Booking | None | Dashboard Bookings | Exists | Add filters/pagination |
| Booking quote | POST | `/v1/bookings/quote` | Price quote before booking | listingId, roomId, dates, guests | Quote | Tourist | `booking.create` | Listing, Room | Select Room | None | Missing | Required for PDF page 23 |
| Booking cancel | PATCH | `/v1/bookings/:id/cancel` | Cancel booking | reason | Booking | Tourist/Support | `booking.create` or support update | Booking, AuditLog | Booking detail | Dashboard Bookings | Missing | Add policy |
| Payment | POST | `/v1/payments/intents` | Create payment intent | bookingId, idempotencyKey | PaymentIntent | Tourist | `payment.create.own` | PaymentIntent, Booking | Payment flow missing | Payments | Exists | Add mobile checkout |
| Payment admin | GET | `/v1/payments` | List payments | none | PaymentIntent[] | Finance/Admin | `payment.read.all` | PaymentIntent | None | Payments | Exists | Add filters |
| Refunds | GET/POST | `/v1/refunds`, `/v1/refunds/mine`, approve | Manage refunds | reason/payment | Refund | Tourist/Finance | `refund.create`, `refund.approve` | Refund, PaymentIntent | Missing refund UI | Refunds | Exists | Add mobile refund request |
| Orders | GET/POST/PATCH | `/v1/orders...` | Food/pharmacy/grocery/SIM orders | order/cart/status | Order | Tourist/Provider/Driver/Admin | order permissions | Order, OrderItem | Food/Grocery/Pharmacy/SIM | Orders | Missing | Add Orders module and OrderItem |
| Taxi | POST | `/v1/taxi/estimate` | Estimate ride | pickup,destination,tier | estimate | Tourist | `booking.create` | Listing, Booking? | Taxi screen | Taxi ops | Missing | Add Taxi module |
| Taxi | POST | `/v1/taxi/book` | Book ride | pickup,destination,tier,payment | booking | Tourist | `booking.create` | Booking, assignment model | Taxi screen | Taxi ops | Missing | Add driver assignment |
| Taxi | PATCH | `/v1/taxi/bookings/:id/status` | Driver/status updates | status | booking | Driver/Provider/Admin | driver assigned permission missing | Booking | Driver app | Taxi ops | Missing | Add driver role/data scope |
| Food | GET | `/v1/food/restaurants` | Restaurant list | filters | restaurants | Guest | Public | Listing/Business | Food | Listings/Orders | Missing | Alias listing kind restaurant |
| Food | GET | `/v1/food/restaurants/:id/menu` | Menu | none | menu items | Guest | Public | Menu/Product missing | Food detail | Provider menu | Missing | Add product/menu model |
| Food | POST | `/v1/food/orders` | Create food order | cart/address/payment | Order | Tourist | `order.create` | Order, OrderItem | Food cart | Orders | Missing | Add order flow |
| Pharmacy | GET | `/v1/pharmacy/items` | Pharmacy catalog | filters | items | Guest | Public | Product missing | Pharmacy | Products | Missing | Add product model |
| Pharmacy | POST | `/v1/pharmacy/prescriptions` | Private prescription upload | file, notes | prescription | Tourist | upload/prescription permission missing | UploadFile, Prescription missing | Pharmacy | Pharmacy orders | Missing | Add private upload flow |
| Pharmacy | POST | `/v1/pharmacy/orders` | Create pharmacy order | cart/prescription | Order | Tourist | `order.create` | Order, OrderItem | Pharmacy | Orders | Missing | Add order flow |
| Grocery | GET | `/v1/grocery/products` | Grocery product catalog | filters | products | Guest | Public | Product missing | Grocery | Products | Missing | Add product model |
| Grocery | POST | `/v1/grocery/orders` | Grocery order | cart/address | Order | Tourist | `order.create` | Order, OrderItem | Grocery | Orders | Missing | Add order flow |
| SIM | GET | `/v1/sim/plans` | SIM plans | provider filters | plans | Guest | Public | Listing SIM_PLAN | SIM | Listings/SIM | Missing alias | Add alias and richer plan metadata |
| SIM | POST | `/v1/sim/orders` | SIM/eSIM order | plan,type,delivery | Order | Tourist | `order.create` | Order, OrderItem | SIM | Orders | Missing | Add activation status |
| Emergency | GET | `/v1/emergency?country=AE` | Emergency numbers | country | EmergencyNumber[] | Guest | Public | EmergencyNumber | Emergency | Missing admin page | Exists | Add admin CRUD |
| Emergency | POST | `/v1/emergency/location-share` | Share location with emergency flow | location | ok/log | Guest/Tourist | Public or safety permission | AuditLog/EmergencyLog missing | Emergency | Emergency logs | Missing | Add privacy-safe endpoint |
| Trip | POST | `/v1/trip-planner/generate` | Generate itinerary | cityIds, dates, party, interests, budget, pace | Trip with steps | Tourist | `trip.create.own` | Trip, TripStep | Trip Step 3 | Analytics missing | Exists | Add draft/premium variants |
| Trip | GET | `/v1/trip-planner/plans` | List own trips | none | Trip[] | Tourist | `trip.read.own` | Trip, TripStep | Saved/Trips later | Analytics missing | Exists | Use in saved trips tab |
| Trip | GET | `/v1/trip-planner/plans/:id` | Own trip detail | id | Trip | Tourist | `trip.read.own` | Trip, TripStep | Itinerary Result | Analytics missing | Exists | None |
| Trip draft | POST/PATCH | `/v1/trip-planner/draft` | Save planner draft | step fields | Trip draft | Tourist | `trip.create.own`/`trip.update.own` | Trip | Trip steps | Analytics | Missing | Add draft endpoints |
| Trip update/delete | PATCH/DELETE | `/v1/trip-planner/plans/:id` | Edit/delete itinerary | fields | Trip/void | Tourist | `trip.update.own` | Trip, TripStep | Result/Edit | Analytics | Missing | Add endpoints |
| Translator | POST | `/v1/translator/image` | OCR/translate image | imageBase64,target | TranslationJob | Tourist | currently `profile.read.own` | TranslationJob | Translator | Analytics missing | Exists | Add `translator.use.own` permission |
| Translator | GET | `/v1/translator/history` | Translation history | none | TranslationJob[] | Tourist | currently `profile.read.own` | TranslationJob | History | Analytics missing | Exists | Add analytics/support privacy policy |
| Translator | DELETE | `/v1/translator/history/:id` | Delete translation | id | void | Tourist | currently `profile.read.own` | TranslationJob | History | None | Exists | Add dedicated permission |
| Provider | GET | `/v1/businesses` | Assigned/all businesses | none | Business[] | Provider/Admin | `business.read.assigned`/`business.read.all` | Business, UserMembership | None | Businesses/Partners | Exists | Add provider-specific dashboard UX |
| Provider listings | POST/PATCH/DELETE | `/v1/provider/listings...` | Manage own listings | listing fields | Listing | Provider | `listing.update.assigned` | Listing | None | Listings | Missing | Add CRUD with scope |
| Provider orders | PATCH | `/v1/provider/orders/:id/status` | Update own order status | status | Order | Provider | `order.read.assigned`/manage missing | Order | None | Orders | Missing | Add Orders module/scope |
| Admin users | GET | `/v1/users` | List users | none | users | Admin | `user.read.all` | User | None | Users | Exists | Add admin namespace/updates |
| Admin roles | GET | `/v1/roles` | List roles/permissions | none | roles | Admin | `role.read.all` | Role, Permission | None | Roles | Exists | Add create/update role endpoints |
| Admin permissions | GET | `/v1/permissions` | Permission catalog | none | permissions | Admin | `permission.read.all` | Permission | None | Permissions | Exists | Add permission builder if needed |
| Audit | GET | `/v1/audit-logs` | Audit logs | filters | AuditLog[] | Support/Finance/Admin | `audit.read.*` | AuditLog | None | Audit Logs | Exists | Add export/filter |
| Support | POST/GET/PATCH | `/v1/support/tickets...` | Support tickets | subject/message/status | Ticket | Tourist/Support | ticket permissions | SupportTicket, TicketMessage | Profile Help | Support dashboard | Missing | Add Support module |
| Notifications | GET/PATCH | `/v1/notifications...` | Notifications | read state | Notification[] | User | notification perms missing | Notification missing | Settings/Profile | Dashboard optional | Missing | Add model/module |
| Uploads | POST | `/v1/uploads` | Avatars/prescriptions/private files | multipart/base64 | UploadFile | User/Provider | upload perms missing | UploadFile missing | Profile/Pharmacy | Admin/provider | Missing | Add storage provider + private access |

## Phase One Contract Decisions

| Decision area | Best decision for Navi Phase One | Why it matters | Documentation or implementation required |
|---|---|---|---|
| API prefix | Keep `/v1` internally and optionally add `/api` gateway aliases later | Avoids churn in working clients while preserving future prompt-compatible public paths | Document in API README and generated OpenAPI |
| Social auth buttons | Feature-flag or hide until provider credentials and callbacks exist | Visible social buttons cannot be fake in demo | Add feature flags or implement provider endpoints |
| Payments | Keep mock payment provider clearly labeled as non-production; do not show fake paid checkout | Investor/demo trust depends on honest payment readiness | Add payment abstraction docs and key checklist |
| Orders | Implement a shared Orders module before food/pharmacy/grocery/SIM UI claims | All service commerce flows depend on `Order` and `OrderItem` | Add order schema, APIs, provider/admin dashboards, tests |
| Provider operations | Add provider namespace with ownership scope before provider dashboard claims | Partners must only see and update their own data | Add provider controllers, scope tests, dashboard routes |
| Prescription uploads | Build private uploads and prescription request workflow before enabling pharmacy purchase | Privacy, compliance, and partner workflow risk | Add `UploadFile`, prescription model, storage access policy |
| Admin content | Add CMS APIs and dashboard pages before claiming mobile content is manageable | Mobile PDF content must be admin-updatable | Add banners, onboarding, marketing APIs and dashboard pages |
| Role writes | Restrict Admin and reserve system writes for Super Admin | Admin wildcard conflicts with Super Admin promise | Remove Admin wildcard, add role update APIs and audit logs |