1. legacy
Itinera API
  • ✈ Itinera API Documentation
  • Docs
    • legacy
      • Itinera — System Overview
      • Technology Stack & Architecture
      • Getting Started Guide
      • Infrastructure
      • Frontend Application
      • Architecture Overview
      • API Reference
      • Backend Services
      • Development Guidelines
    • phases
      • 01. Architecture Overview & Checkout Idempotency
      • Phase 2: Commerce & Checkout Engine
      • Phase 3: Webhooks & Asynchronous Fulfillment
      • Phase 4: Security Perimeter & Authentication
      • Phase 5: Database Schema & Entity Relationships
      • Phase 6: AI Quota & Telemetry Subsystems
      • Phase 7: API Route Matrix & FormRequests
      • Phase 8: Global Exception & Error Handling
      • Phase 9: Frontend Ecosystem & State Management
      • Phase 10: Design System & Component Library
      • Phase 11: Interactive GSAP Animations
      • Phase 12: Deployment & CI/CD Pipeline
      • Phase 13: Testing Strategies
      • Phase 14: Performance & Optimization
      • Phase 15: Developer Onboarding & Runbooks
      • 15-Phase Comprehensive Wiki & Documentation Plan
  • APIs
    • Auth
      • Register a new user
      • Log in a user
      • Log out user
      • Refresh JWT token
      • Forgot password request
      • Reset password verification
      • Get current user profile
      • Update user profile
      • Redirect to Google OAuth
      • Google OAuth Callback
      • Verify email via signed URL
    • Catalog
      • List all countries
      • Get country details
      • List all cities
      • List all regions
      • List all destinations
      • Get destination details
      • Get hotels by destination
      • List all hotels
      • Get hotel details
      • Get reviews for a hotel
      • List all flights
      • Get flight details
      • List all restaurants
      • Get restaurant details
      • List all attractions
      • Get current weather
      • Submit review for an entity
      • Delete review
      • Toggle favourite status for entity
      • List my submitted reviews
    • Bookings
      • Book a tour destination
    • V1 Aliases
      • V1 List all countries
      • V1 Get country details
      • V1 List all cities
      • V1 List all destinations
      • V1 Get destination details
      • V1 Get hotels by destination
      • V1 List all hotels
      • V1 Get hotel details
      • V1 Get reviews for a hotel
      • V1 List all flights
      • V1 Get flight details
      • V1 List all restaurants
      • V1 Get restaurant details
      • V1 List all attractions
      • V1 Get attraction details
      • V1 List all regions
      • V1 Get weather details
    • Trips
      • List user trips
      • Create a new trip
      • Get trip details
      • Update trip details
      • Delete a trip
      • Get creation metadata
      • Attach items to a trip
      • Update trip item
      • Detach items from a trip
      • Fork a trip
    • Conversations
      • List user conversations
      • Start a new conversation
      • Get conversation details
      • List messages in conversation
      • Send message to conversation
      • Mark conversation as read
    • Commerce Plans
      • List public plans
      • Get public plan details
    • Commerce Subscriptions
      • Subscribe to a plan
      • Upgrade active plan
      • Get active subscription info
      • Cancel active subscription
    • Commerce Checkout
      • Initiate Paymob payment checkout
    • Integrations
      • Paymob status webhook callback
      • Paymob redirect return callback
    • System Settings & Support
      • Submit public contact message
      • Subscribe to system newsletter
      • Get list of my reports
      • List all notifications
      • Mark single notification as read
      • List available surveys
      • Submit answers for survey
      • Get survey details
      • Update survey details
      • Delete survey response
    • AI Tools
      • Enhance itinerary details using AI
      • Request AI review of itinerary
      • Plan route using AI assistance
      • Get AI quota remaining details
      • Chat with AI Concierge assistant
      • Get AI Review progress by ID
    • Agency Integration
      • Request agency assignment
      • List agency active tasks
      • List agency managed trips
      • Get agency total earnings
      • Get agency profile details
      • Update agency profile details
    • Admin User Management
      • List users inside admin dashboard
      • Get user profile
      • Set user active status
      • Block user profile
    • Admin Catalog Moderation
      • Create new catalog category
      • Create new catalog destination
      • Create new hotel catalog record
      • Create new flight catalog record
      • Create new restaurant catalog record
      • Create new attraction catalog record
  • Schemas
    • User
    • ErrorResponse
    • Trip
    • Destination
    • Hotel
    • Flight
    • Restaurant
    • Attraction
    • Booking
    • Review
    • Agency
    • Survey
  1. legacy

API Reference

Table of Contents#

1.
Conventions
2.
Authentication
3.
Public Catalog & Content
4.
Trips & AI
5.
Commerce
6.
Social & Community
7.
System Services
8.
Admin Surfaces
9.
Agency Marketplace
10.
Rate Limits
11.
Machine-Readable Docs
Route count at HEAD 0c14fa54: 237 registered routes across 499 lines of routes/api.php.

Conventions#

Base URL <host>/api; JSON bodies; JWT via Authorization: Bearer <token> unless noted public.
Responses wrapped by Support/ApiResponse; resources transformed by app/Http/Resources/*.
Catalog admin mutations support soft-delete + PATCH .../restore.
Legacy aliases exist deliberately (e.g. /review/{id} ⇄ /ai/review/{id}, /orders ⇄ /me/orders) to keep older frontend builds alive.

Authentication#

MethodPathNotes
POST/register, /loginthrottled (throttle:register, throttle:login)
POST/forgot-password, /reset-passwordtoken mail flow, throttled
GET/email/verify/{id}/{hash}signed verification link
GET/auth/google, /auth/facebook (+ callbacks)Socialite redirect flow; completion via POST /auth/social/complete
GET/user · /mecurrent profile
POST/logout, /refreshrefresh throttled 15/min
Middleware chain on protected groups: auth:api → verified → active (custom) → permission/role.

Public Catalog & Content#

GET /categories, /countries, /cities, /destinations, /hotels, /flights, /restaurants, /attractions, /regions, /stats/summary, /site-settings — all public read-only, each with {id} detail variants and relation endpoints (/destinations/{d}/hotels, /hotels/{h}/reviews). Weather: GET /weather (cached + throttled). Maps: GET /maps/destination/{destination} public-throttled; GET /maps/trip/{trip} authed.

Trips & AI#

MethodPathPurpose
CRUD/trips, /planner/*create/update/delete trips, itinerary items attach/detach/update, POST /trips/{trip}/fork community fork
POST/enhance, /review, /trips/generate-ai (+aliases)Groq-backed text enhance, AI review, itinerary generation — quota-metered
GET/POST/reviews/{type}/{id}, /me/reviewsentity reviews + personal review management

Commerce#

Plans: GET /plans[/id] public; authed POST /me/subscribe, /me/upgrade, /me/subscription/cancel, GET /me/subscription.
Checkout: POST /payments/initiate (strategy-routed); webhooks POST /payments/webhook + /paymob/webhook + versioned v1 alias (CSRF-exempt, HMAC-verified); browser GET /callback variants.
Orders: GET /orders ⇄ /me/orders, lookup GET /orders/lookup/{orderRef}.

Social & Community#

Chat: /conversations CRUD-ish group (index/store/show/messages/read). Favourites: POST /favourites/{type}/{id} toggle. Flags: POST /agency-assignments/{assignment}/report.

System Services#

Surveys (apiResource /surveys + answer routes), contact POST /contacts, newsletter POST /newsletter/subscribe, notifications (GET /notifications, mark read/all-read), user dashboard (GET /dashboard, /favourites, /orders, /me/ai-quota), reports GET /me/reports, settings GET|PUT /settings, site settings public.

Admin Surfaces#

All behind permission:* or role:admin|super_admin:
AreaRoutes
Users/users CRUD + `PATCH /users/{u}/active
Catalogadmin CRUD × categories, countries, destinations, flights, hotels, attractions, restaurants (+restore)
Trips/Reviews/admin/trips, /admin/reviews approve/reject/restore
Moderation/flags approve/decline
Analytics/analytics, /analytics/revenue
PlansPOST /admin/set-plans
Reports/admin/reports index/generate/download
Inbox/admin/notifications, /contacts read/resolve
SettingsPUT /settings, PATCH /settings/{key}
Agency intake/admin/agency-requests, approve endpoint

Agency Marketplace#

Authed role agency|admin|super_admin: assignments list, approve/decline, trip creation, earnings, profile get/update; user-side POST /agency-requests, /agency-assignments/{a}/cancel.

Rate Limits#

Named limiter usage: register, login (3/10min forgot, 5/min reset), weather, maps, ai, contacts, newsletter, refresh 15/min. Definitions live in a service provider/bootstrap limiter registration; abuse covered by tests (WeatherAbuseTest, AiRateLimitTest, CheckoutAbuseTest).

Machine-Readable Docs#

Interactive OpenAPI (Scramble): http://127.0.0.1:8000/docs/api
Hand-written reference: docs/Conference-API-Documentation.md + branded PDF
Postman collection generator: php artisan export:postman
Permission audit matrix: docs/ROUTES-PERMISSIONS-AUDIT.md
Modified at 2026-08-25 22:41:45
Previous
Architecture Overview
Next
Backend Services
Built with