Agamnos API

Base URL, auth, OpenAPI, public booking, webhooks, and staff routes.

Distribution·Owner·Updated 2026-09-28

Agamnos API is the Nest HTTP surface for the console, Agamnos Direct, payment webhooks, Rasnos folio posts, and partner integrations.

Global prefix is /api/v1. Interactive OpenAPI lives at /api/docs on the API host (not under /api/v1).

The browser console calls same-origin /api/v1 (Next proxies to the API). Server-side and scripts use NEXT_PUBLIC_API_URL, e.g. http://localhost:4000/api/v1 locally.

Staff routes require a JWT from login. Public booking and processor webhooks do not use staff tokens. Permissions on the JWT (for example front-desk, payment:process, report:view) match the console sidebar.

How to

  1. Open /api/docs on the API host for the live schema and try requests.
  2. Staff: POST /api/v1/auth/login with email and password → use accessToken as Authorization: Bearer on protected routes; refresh with POST /api/v1/auth/refresh.
  3. Direct partners: call /api/v1/public/properties/{code}/… then quote and reservations; send Idempotency-Key on book.
  4. Payment processors: point webhooks at /api/v1/payments/webhooks/stripe or …/razorpay with the hotel’s signing secret from Property settings.
  5. Health check (no auth): GET /api/v1/health.

Technical

  • Auth: POST /api/v1/auth/login | /auth/register | /auth/refresh (public); GET /api/v1/auth/me (Bearer).
  • Public booking: GET /api/v1/public/properties/:idOrCode, …/room-types, …/availability; POST …/booking/quote; POST …/reservations (+ Idempotency-Key).
  • Display FX (optional): GET /api/v1/public/fx?from=&to= — approximate guest display only; rates and charges stay in Property.currency.
  • Payments: GET /api/v1/payments/config; POST /api/v1/payments/confirm; POST /api/v1/payments/webhooks/stripe|razorpay; staff POST /api/v1/payments and …/:id/refund.
  • Front desk / PMS examples (Bearer + permissions): /api/v1/front-desk/dashboard, /front-desk/tape-chart, /reservations, /rates, /rooms, /guests, /reports/…
  • Room service: staff /api/v1/room-service/*; Rasnos folio POST /api/v1/folio/charge with x-api-key.
  • Connect: GET /api/v1/channels/providers (public); GET /api/v1/channels (staff).
  • CORS allowlist includes the platform domain, configured API_CORS_ORIGIN, localhost ports in non-production, and *.vercel.app. Credentials supported for cookie/session-style clients.
  • JSON bodies are validated (whitelist + forbid unknown fields). Prefer ISO date strings for stay nights; property currency and timezone come from the property record.

FAQ

Where is the OpenAPI UI?
On the API host at /api/docs (for example http://localhost:4000/api/docs). Production API host is documented in deploy notes.
Why does the browser use /api/v1 without a host?
Same-origin proxy avoids CORS blocks from custom booking domains. Scripts and mobile clients should use the absolute API base URL.
Can partners invent stock outside the PMS?
No. Public book and Connect sync must consume central inventory. Double-selling is prevented by the same availability path as the desk.

See also: Agamnos Direct · Agamnos Pay · Agamnos Connect · Room service · Security and privacy · Product suite

All topics← Agamnos Pay