# Travnet Search Engine (TSE)

> A multi-supplier travel platform by Sitenet Tech for travel enterprises and tour operators.
> Search. Book. Manage. Flight, hotel and transport search across multiple GDS and aggregator
> suppliers, followed by booking, ticketing, payment and post-sale servicing, plus admin,
> agency and traveller management surfaces.

## Hosts

- Production: `https://api.travnet.app`
- Test: `https://test.travnet.app`
- Console and reference: `https://developers.travnet.app`

## Authentication

Supabase-backed JWT bearer tokens.

1. `POST /api/v1/auth/login` with `{"email": "...", "password": "..."}`
2. Read `access_token` from the response.
3. Send `Authorization: Bearer <access_token>` on every subsequent request.

Guard levels used below:
- `role` — restricted to a specific role via RoleGuard (super_admin, company_admin, company_staff, customer)
- `user` — any authenticated caller
- `none` — no authentication required
- `tenant` — additionally scoped to the caller's company
- `idem` — requires an `Idempotency-Key` request header
- `sse` — responds with `text/event-stream`, not JSON

## Conventions

- All monetary amounts are integers in MINOR units (45000 = 450.00) on fields suffixed `_minor`.
- Currencies: GBP, USD, EUR, BDT, SAR, AED, BHD, QAR, KWD, OMR, PKR, INR, MYR, SGD, LKR.
- Dates are ISO 8601 (`YYYY-MM-DD`); timestamps are RFC 3339 UTC.
- List endpoints take `page` and `page_size`, and usually `sort_by` / `sort_order`.
- Any operation that creates or moves money requires an `Idempotency-Key`; reuse of a key
  returns the original result rather than repeating the effect.
- Search is asynchronous: POST a search, receive a `search_id`, then either poll the `batch`
  endpoint or consume the SSE `stream` endpoint.

## Machine-readable

- OpenAPI 3.1 schema: https://developers.travnet.app/openapi.json
- Full endpoint reference: https://developers.travnet.app/llms-full.txt


## Endpoints


### Search (16)


#### Flight search

- `POST /api/v1/flight/getFare` [user] — Initiate flight search
- `GET /api/v1/flight/getFare/batch/{search_id}` [user] — Get all results at once (batch mode)
- `GET /api/v1/flight/getFare/stream-by-gds/{search_id}` [user, sse] — Stream flight results grouped by GDS
- `GET /api/v1/flight/getFare/stream/{search_id}` [user, sse] — Stream flight search results

#### Hotel search

- `POST /api/v1/hotel/search` [user] — Initiate hotel availability search
- `GET /api/v1/hotel/search/batch/{search_id}` [user] — Get all hotel results at once (batch mode)
- `GET /api/v1/hotel/search/results/{search_id}` [user] — Poll hotel search results
- `GET /api/v1/hotel/search/stream-by-provider/{search_id}` [user, sse] — Stream hotel results grouped by provider
- `GET /api/v1/hotel/search/stream/{search_id}` [user, sse] — Stream hotel offers via SSE (offer-by-offer)

#### Reference data

- `GET /api/v1/airlines/search` [none] — Search Airlines
- `GET /api/v1/airports/search` [none] — Search Airports

#### Transport search

- `POST /api/v1/transport/search` [user] — Initiate ground transport search
- `GET /api/v1/transport/search/batch/{search_id}` [user] — Get all transport results at once (batch mode)
- `GET /api/v1/transport/search/results/{search_id}` [user] — Poll transport search results
- `GET /api/v1/transport/search/stream-by-provider/{search_id}` [user, sse] — Stream transport results grouped by provider
- `GET /api/v1/transport/search/stream/{search_id}` [user, sse] — Stream transport offers via SSE (offer-by-offer)

### Operations (44)


#### Ancillaries

- `POST /api/v1/bookings/{booking_id}/ancillaries` [user] — Add an ancillary SSR (extra baggage, meal, wheelchair…)
- `POST /api/v1/bookings/{booking_id}/ancillaries/cancel` [user] — Cancel paid ancillaries (void EMD or remove the element)
- `GET /api/v1/bookings/{booking_id}/ancillaries/catalogue` [user] — List purchasable ancillaries (paid bags / seats / meals)
- `POST /api/v1/bookings/{booking_id}/ancillaries/emd` [user] — Issue EMD(s) for priced ancillaries
- `POST /api/v1/bookings/{booking_id}/ancillaries/purchase` [user] — Book + price paid ancillaries (creates TSMs)

#### Baggage

- `POST /api/v1/bookings/bags/catalogue` [user] — Bag catalogue for a flight offer (pricing?include=bags)
- `POST /api/v1/bookings/bags/reprice` [user] — Re-price a flight offer with chosen bags
- `GET /api/v1/bookings/{booking_id}/baggage` [user] — Get baggage allowances

#### Booking servicing

- `GET /api/v1/bookings/{booking_id}/servicing` [user] — List post-ticketing requests

#### Create & price

- `POST /api/v1/bookings/createPnr` [user, idem] — Create PNR/Booking
- `POST /api/v1/bookings/fareRules` [user] — Get fare rules for an offer
- `POST /api/v1/bookings/revalidation` [user] — Revalidate flight offer price
- `POST /api/v1/bookings/upsell` [user] — Branded-fare upsell for a flight offer

#### Flight bookings

- `GET /api/v1/bookings/{booking_id}` [user] — Get booking details
- `POST /api/v1/bookings/{booking_id}/authorize` [user, idem] — Authorize payment for booking
- `POST /api/v1/bookings/{booking_id}/cancel` [user] — Cancel booking
- `PATCH /api/v1/bookings/{booking_id}/commission` [user] — Add FM (agency) commission to an order
- `PATCH /api/v1/bookings/{booking_id}/foid` [user] — Add Form of Identification (FOID) to an order
- `POST /api/v1/bookings/{booking_id}/notes` [user] — Attach notes to the booking at the provider
- `GET /api/v1/bookings/{booking_id}/order` [user] — Retrieve flight order by reference
- `GET /api/v1/bookings/{booking_id}/order/by-reference` [user] — Retrieve flight order by record locator (by-reference)
- `GET /api/v1/bookings/{booking_id}/rules` [user] — Get fare rules for booking

#### Hotel operations

- `POST /api/v1/hotel/book` [user, idem] — Create hotel booking
- `GET /api/v1/hotel/bookings` [user] — List my hotel bookings
- `GET /api/v1/hotel/bookings/{booking_id}` [user] — Get hotel booking details
- `POST /api/v1/hotel/bookings/{booking_id}/cancel` [user] — Cancel hotel booking
- `POST /api/v1/hotel/check-rate` [user] — Re-validate hotel rate

#### Payments

- `POST /api/v1/bookings/{booking_id}/payment/capture` [user, idem] — Capture authorized payment
- `GET /api/v1/bookings/{booking_id}/payment/history` [user] — Get payment transaction history
- `POST /api/v1/bookings/{booking_id}/payment/refund` [user, idem] — Refund captured payment
- `POST /api/v1/bookings/{booking_id}/payment/void` [user, idem] — Void (cancel) authorized payment

#### Seats

- `GET /api/v1/bookings/{booking_id}/seats` [user] — Get seat map for booking
- `POST /api/v1/bookings/{booking_id}/seats` [user] — Select seat for passenger
- `POST /api/v1/bookings/{booking_id}/seats/batch` [user] — Reserve several seats in one GDS session
- `POST /api/v1/bookings/{booking_id}/seats/issue` [user] — Pay for the seats held on a booking (price + EMD)

#### Ticketing

- `POST /api/v1/bookings/{booking_id}/ticket` [user, idem] — Issue e-tickets
- `GET /api/v1/bookings/{booking_id}/ticket/document` [user] — Get the e-ticket document (coupons)
- `GET /api/v1/bookings/{booking_id}/ticket/status` [user] — Live ticket-order status
- `POST /api/v1/bookings/{booking_id}/ticket/{action}` [user] — Void, refund, or price a reissue on an issued ticket (quote-first)

#### Transport operations

- `POST /api/v1/transport/book` [user, idem] — Book a ground transfer
- `GET /api/v1/transport/bookings` [user] — List my transport bookings
- `GET /api/v1/transport/bookings/{booking_id}` [user] — Get transport booking details
- `POST /api/v1/transport/bookings/{booking_id}/cancel` [user] — Cancel transport booking
- `POST /api/v1/transport/quote` [user] — Re-validate transport quote

### Admin (46)


#### Companies

- `GET /api/v1/admin/companies` [role, tenant] — List all companies
- `POST /api/v1/admin/companies` [role, tenant] — Create a new company
- `DELETE /api/v1/admin/companies/{company_id}` [role, tenant] — Soft-delete company
- `GET /api/v1/admin/companies/{company_id}` [role] — Get company details
- `PATCH /api/v1/admin/companies/{company_id}` [role, tenant] — Update company details
- `POST /api/v1/admin/companies/{company_id}/activate` [role, tenant] — Re-activate a suspended company
- `POST /api/v1/admin/companies/{company_id}/suspend` [role, tenant] — Suspend a company

#### Flight bookings

- `GET /api/v1/admin/bookings` [role, tenant] — List all bookings
- `GET /api/v1/admin/bookings/reconciliation` [role] — View reconciliation queue
- `GET /api/v1/admin/bookings/{booking_id}` [role] — Get booking details
- `POST /api/v1/admin/bookings/{booking_id}/override-status` [role, tenant] — Override booking status
- `POST /api/v1/admin/bookings/{booking_id}/reconcile` [role, tenant] — Trigger manual reconciliation

#### GDS operations

- `GET /api/v1/admin/gds/circuit-breakers` [role] — Circuit breaker states
- `GET /api/v1/admin/gds/performance` [role] — GDS performance metrics
- `GET /api/v1/admin/gds/status` [role] — GDS provider health overview
- `PATCH /api/v1/admin/gds/{provider}/config` [role] — Update GDS configuration
- `POST /api/v1/admin/gds/{provider}/reset-circuit` [role] — Reset circuit breaker

#### Hotel bookings

- `GET /api/v1/admin/hotel-bookings` [role, tenant] — List all hotel bookings
- `GET /api/v1/admin/hotel-bookings/stats/summary` [role] — Hotel bookings statistics
- `GET /api/v1/admin/hotel-bookings/{booking_id}` [role] — Get hotel booking details
- `POST /api/v1/admin/hotel-bookings/{booking_id}/override-status` [role, tenant] — Override hotel booking status

#### Markup rules

- `GET /api/v1/admin/markup-rules` [role] — List markup rules
- `POST /api/v1/admin/markup-rules` [role] — Create markup rule
- `POST /api/v1/admin/markup-rules/calculate` [role] — Calculate markup for a price
- `DELETE /api/v1/admin/markup-rules/{rule_id}` [role] — Delete markup rule (soft)
- `PATCH /api/v1/admin/markup-rules/{rule_id}` [role] — Update markup rule

#### Payments

- `GET /api/v1/admin/payments` [role] — List all payments
- `GET /api/v1/admin/payments/settlement-report` [role] — Settlement report
- `POST /api/v1/admin/payments/{payment_id}/manual-refund` [role, tenant] — Process manual refund

#### Reports

- `GET /api/v1/admin/reports/audit` [role] — Audit log
- `GET /api/v1/admin/reports/dashboard` [role] — Platform dashboard KPIs
- `GET /api/v1/admin/reports/live` [role] — Live system status
- `GET /api/v1/admin/reports/revenue` [role] — Revenue report

#### System

- `GET /api/v1/admin/system/cache-stats` [role] — Cache statistics
- `POST /api/v1/admin/system/clear-cache` [role] — Invalidate cache keys
- `GET /api/v1/admin/system/error-logs` [role] — System error logs
- `GET /api/v1/admin/system/health` [role] — System component health

#### Transport bookings

- `GET /api/v1/admin/transport-bookings` [role, tenant] — List all transport bookings
- `GET /api/v1/admin/transport-bookings/stats/summary` [role] — Transport bookings statistics
- `GET /api/v1/admin/transport-bookings/{booking_id}` [role] — Get transport booking details
- `POST /api/v1/admin/transport-bookings/{booking_id}/override-status` [role, tenant] — Override transport booking status

#### Users

- `GET /api/v1/admin/users` [role] — List all users
- `GET /api/v1/admin/users/{user_id}` [role] — Get user details
- `PATCH /api/v1/admin/users/{user_id}` [role, tenant] — Admin update user
- `POST /api/v1/admin/users/{user_id}/impersonate` [role, tenant] — Impersonate user
- `POST /api/v1/admin/users/{user_id}/suspend` [role, tenant] — Suspend user

### Company (33)


#### Clients

- `GET /api/v1/company/clients` [role, tenant] — List company clients
- `POST /api/v1/company/clients` [role, tenant] — Create client
- `GET /api/v1/company/clients/{client_id}` [role, tenant] — Get client details
- `PATCH /api/v1/company/clients/{client_id}` [role, tenant] — Update client
- `GET /api/v1/company/clients/{client_id}/bookings` [role, tenant] — Get client's bookings

#### Flight bookings

- `GET /api/v1/company/bookings` [role, tenant] — List company bookings
- `GET /api/v1/company/bookings/pending` [role, tenant] — Bookings requiring action
- `GET /api/v1/company/bookings/{booking_id}` [role, tenant] — Get booking detail
- `POST /api/v1/company/bookings/{booking_id}/assign` [role, tenant] — Assign booking to staff

#### Hotel bookings

- `GET /api/v1/company/hotel-bookings` [role, tenant] — List company hotel bookings
- `GET /api/v1/company/hotel-bookings/pending` [role, tenant] — Hotel bookings requiring action
- `GET /api/v1/company/hotel-bookings/{booking_id}` [role, tenant] — Get hotel booking detail

#### Markup rules

- `GET /api/v1/company/markup-rules` [role, tenant] — List company markup rules
- `POST /api/v1/company/markup-rules` [role, tenant] — Create company markup rule
- `DELETE /api/v1/company/markup-rules/{rule_id}` [role, tenant] — Delete company markup rule
- `PATCH /api/v1/company/markup-rules/{rule_id}` [role, tenant] — Update company markup rule

#### Profile & settings

- `GET /api/v1/company/profile` [role, tenant] — Get company profile
- `PATCH /api/v1/company/profile` [role, tenant] — Update company profile
- `GET /api/v1/company/profile/settings` [role, tenant] — Get company settings
- `PATCH /api/v1/company/profile/settings` [role, tenant] — Update company settings

#### Reports

- `GET /api/v1/company/reports/dashboard` [role, tenant] — Company dashboard KPIs
- `GET /api/v1/company/reports/sales` [role, tenant] — Sales report
- `GET /api/v1/company/reports/top-clients` [role, tenant] — Top clients by revenue
- `GET /api/v1/company/reports/top-routes` [role, tenant] — Top routes by bookings

#### Staff

- `GET /api/v1/company/staff` [role, tenant] — List company staff
- `POST /api/v1/company/staff/invite` [role, tenant] — Invite new staff member
- `PATCH /api/v1/company/staff/{staff_id}` [role, tenant] — Update staff member
- `POST /api/v1/company/staff/{staff_id}/deactivate` [role, tenant] — Deactivate staff member

#### Transport bookings

- `GET /api/v1/company/transport-bookings` [role, tenant] — List company transport bookings
- `GET /api/v1/company/transport-bookings/pending` [role, tenant] — Transport bookings requiring action
- `GET /api/v1/company/transport-bookings/{booking_id}` [role, tenant] — Get transport booking detail

#### Wallet

- `GET /api/v1/company/wallet` [role, tenant] — Get wallet balance
- `GET /api/v1/company/wallet/transactions` [role, tenant] — Transaction ledger

### Customer (19)


#### Flight bookings

- `GET /api/v1/customer/bookings` [role, tenant] — My bookings
- `GET /api/v1/customer/bookings/{booking_id}` [role, tenant] — Booking detail
- `POST /api/v1/customer/bookings/{booking_id}/cancel` [role, tenant] — Request cancellation

#### Hotel bookings

- `GET /api/v1/customer/hotel-bookings` [role, tenant] — My hotel bookings
- `GET /api/v1/customer/hotel-bookings/{booking_id}` [role, tenant] — Hotel booking detail
- `POST /api/v1/customer/hotel-bookings/{booking_id}/cancel` [role, tenant] — Cancel hotel booking

#### Payments

- `GET /api/v1/customer/payments` [role, tenant] — My payment history
- `GET /api/v1/customer/payments/receipts/{payment_id}` [role, tenant] — Get payment receipt

#### Profile

- `GET /api/v1/customer/profile` [role, tenant] — Get my profile
- `PATCH /api/v1/customer/profile` [role, tenant] — Update my profile
- `GET /api/v1/customer/profile/preferences` [role, tenant] — Get my preferences
- `PATCH /api/v1/customer/profile/preferences` [role, tenant] — Update my preferences

#### Transport bookings

- `GET /api/v1/customer/transport-bookings` [role, tenant] — My transport bookings
- `GET /api/v1/customer/transport-bookings/{booking_id}` [role, tenant] — Transport booking detail
- `POST /api/v1/customer/transport-bookings/{booking_id}/cancel` [role, tenant] — Cancel transport booking

#### Travelers

- `GET /api/v1/customer/travelers` [role, tenant] — List saved travelers
- `POST /api/v1/customer/travelers` [role, tenant] — Save a new traveler
- `DELETE /api/v1/customer/travelers/{traveler_id}` [role, tenant] — Delete saved traveler
- `PATCH /api/v1/customer/travelers/{traveler_id}` [role, tenant] — Update saved traveler

### Platform (15)


#### Authentication

- `POST /api/v1/auth/login` [none] — Login User
- `GET /api/v1/auth/me` [user] — Get current user profile
- `POST /api/v1/auth/register` [none] — Register User
- `GET /api/v1/auth/verify-email` [none] — Verify Email

#### Cache & metrics

- `GET /metrics/cache` [none] — Cache Metrics
- `GET /metrics/combined` [none] — Combined Metrics
- `GET /metrics/redis` [none] — Redis Metrics

#### Configuration

- `GET /config` [none] — Get Configuration

#### Health

- `GET /api/v1/health/` [none] — Health probe (router root alias)
- `GET /api/v1/health/health` [none] — System Health Check
- `GET /health/` [none] — Health probe (router root alias)
- `GET /health/health` [none] — System Health Check

#### Maintenance

- `POST /admin/cache/clear` [none] — Clear Cache
- `POST /admin/maintenance/run` [none] — Run Maintenance

#### Service info

- `GET /` [none] — Root


---
(c) Sitenet Tech. Generated from the TSE OpenAPI schema.