openapi: 3.0.3 info: title: VIP Coordinator API description: | A comprehensive API for managing VIP transportation coordination, including flight tracking, driver management, and event scheduling for high-profile guests. ## Features - VIP management with flight and self-driving transport modes - Real-time flight tracking and validation - Driver assignment and conflict detection - Event scheduling with validation - Admin settings management ## Authentication Most endpoints are public for demo purposes. Admin endpoints require authentication. version: 1.0.0 contact: name: VIP Coordinator Support email: support@vipcoordinator.com license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: http://localhost:3000/api description: Development server - url: https://api.vipcoordinator.com/api description: Production server tags: - name: Health description: System health checks - name: VIPs description: VIP management operations - name: Drivers description: Driver management operations - name: Flights description: Flight tracking and information - name: Schedule description: Event and meeting scheduling - name: Admin description: Administrative operations paths: /health: get: tags: - Health summary: Health check endpoint description: Returns the current status of the API server responses: '200': description: Server is healthy content: application/json: schema: type: object properties: status: type: string example: "OK" timestamp: type: string format: date-time example: "2025-06-01T12:00:00.000Z" /vips: get: tags: - VIPs summary: Get all VIPs description: Retrieve a list of all VIPs in the system responses: '200': description: List of VIPs content: application/json: schema: type: array items: $ref: '#/components/schemas/VIP' post: tags: - VIPs summary: Create a new VIP description: Add a new VIP to the system requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VIPCreate' examples: flight_vip: summary: VIP with flight transport value: name: "John Doe" organization: "Tech Corp" transportMode: "flight" flights: - flightNumber: "UA1234" flightDate: "2025-06-26" segment: 1 needsAirportPickup: true needsVenueTransport: true notes: "CEO - requires executive transport" self_driving: summary: Self-driving VIP value: name: "Jane Smith" organization: "Local Business" transportMode: "self-driving" expectedArrival: "2025-06-26T14:00:00" needsAirportPickup: false needsVenueTransport: true notes: "Driving from Colorado Springs" responses: '201': description: VIP created successfully content: application/json: schema: $ref: '#/components/schemas/VIP' '400': description: Invalid input data /vips/{id}: put: tags: - VIPs summary: Update a VIP description: Update an existing VIP's information parameters: - name: id in: path required: true schema: type: string description: VIP ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VIPCreate' responses: '200': description: VIP updated successfully content: application/json: schema: $ref: '#/components/schemas/VIP' '404': description: VIP not found delete: tags: - VIPs summary: Delete a VIP description: Remove a VIP from the system parameters: - name: id in: path required: true schema: type: string description: VIP ID responses: '200': description: VIP deleted successfully content: application/json: schema: type: object properties: message: type: string example: "VIP deleted successfully" vip: $ref: '#/components/schemas/VIP' '404': description: VIP not found /vips/{vipId}/schedule: get: tags: - Schedule summary: Get VIP's schedule description: Retrieve all scheduled events for a specific VIP parameters: - name: vipId in: path required: true schema: type: string description: VIP ID responses: '200': description: VIP's schedule content: application/json: schema: type: array items: $ref: '#/components/schemas/ScheduleEvent' post: tags: - Schedule summary: Add event to VIP's schedule description: Create a new event for a VIP with validation parameters: - name: vipId in: path required: true schema: type: string description: VIP ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleEventCreate' example: title: "Meeting with CEO" location: "Hyatt Regency Denver" startTime: "2025-06-26T11:00:00" endTime: "2025-06-26T12:30:00" type: "meeting" assignedDriverId: "1748780965562" description: "Important strategic meeting" responses: '201': description: Event created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/ScheduleEvent' - type: object properties: warnings: type: array items: $ref: '#/components/schemas/ValidationWarning' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationError' /vips/{vipId}/schedule/{eventId}: put: tags: - Schedule summary: Update a scheduled event description: Update an existing event in a VIP's schedule parameters: - name: vipId in: path required: true schema: type: string description: VIP ID - name: eventId in: path required: true schema: type: string description: Event ID requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/ScheduleEventCreate' - type: object properties: status: $ref: '#/components/schemas/EventStatus' responses: '200': description: Event updated successfully content: application/json: schema: $ref: '#/components/schemas/ScheduleEvent' '404': description: VIP or event not found delete: tags: - Schedule summary: Delete a scheduled event description: Remove an event from a VIP's schedule parameters: - name: vipId in: path required: true schema: type: string description: VIP ID - name: eventId in: path required: true schema: type: string description: Event ID responses: '200': description: Event deleted successfully '404': description: VIP or event not found /vips/{vipId}/schedule/{eventId}/status: patch: tags: - Schedule summary: Update event status description: Update the status of a specific event parameters: - name: vipId in: path required: true schema: type: string description: VIP ID - name: eventId in: path required: true schema: type: string description: Event ID requestBody: required: true content: application/json: schema: type: object properties: status: $ref: '#/components/schemas/EventStatus' example: status: "in-progress" responses: '200': description: Event status updated content: application/json: schema: $ref: '#/components/schemas/ScheduleEvent' '404': description: VIP or event not found /drivers: get: tags: - Drivers summary: Get all drivers description: Retrieve a list of all drivers in the system responses: '200': description: List of drivers content: application/json: schema: type: array items: $ref: '#/components/schemas/Driver' post: tags: - Drivers summary: Create a new driver description: Add a new driver to the system requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DriverCreate' example: name: "Carlos Rodriguez" phone: "(303) 555-0101" currentLocation: lat: 39.8561 lng: -104.6737 responses: '201': description: Driver created successfully content: application/json: schema: $ref: '#/components/schemas/Driver' /drivers/{id}: put: tags: - Drivers summary: Update a driver description: Update an existing driver's information parameters: - name: id in: path required: true schema: type: string description: Driver ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DriverCreate' responses: '200': description: Driver updated successfully content: application/json: schema: $ref: '#/components/schemas/Driver' '404': description: Driver not found delete: tags: - Drivers summary: Delete a driver description: Remove a driver from the system parameters: - name: id in: path required: true schema: type: string description: Driver ID responses: '200': description: Driver deleted successfully '404': description: Driver not found /drivers/{driverId}/schedule: get: tags: - Drivers summary: Get driver's schedule description: Retrieve all events assigned to a specific driver parameters: - name: driverId in: path required: true schema: type: string description: Driver ID responses: '200': description: Driver's schedule content: application/json: schema: type: object properties: driver: type: object properties: id: type: string name: type: string phone: type: string schedule: type: array items: allOf: - $ref: '#/components/schemas/ScheduleEvent' - type: object properties: vipId: type: string vipName: type: string '404': description: Driver not found /drivers/availability: post: tags: - Drivers summary: Check driver availability description: Find available drivers for a specific time slot requestBody: required: true content: application/json: schema: type: object properties: startTime: type: string format: date-time endTime: type: string format: date-time location: type: string required: - startTime - endTime example: startTime: "2025-06-26T11:00:00" endTime: "2025-06-26T12:30:00" location: "Denver Convention Center" responses: '200': description: Driver availability information content: application/json: schema: type: object properties: available: type: array items: $ref: '#/components/schemas/Driver' busy: type: array items: allOf: - $ref: '#/components/schemas/Driver' - type: object properties: conflictingEvents: type: array items: $ref: '#/components/schemas/ScheduleEvent' /drivers/{driverId}/conflicts: post: tags: - Drivers summary: Check driver conflicts description: Check if a specific driver has conflicts for a time slot parameters: - name: driverId in: path required: true schema: type: string description: Driver ID requestBody: required: true content: application/json: schema: type: object properties: startTime: type: string format: date-time endTime: type: string format: date-time location: type: string required: - startTime - endTime responses: '200': description: Conflict check results content: application/json: schema: type: object properties: conflicts: type: array items: $ref: '#/components/schemas/ScheduleEvent' /flights/{flightNumber}: get: tags: - Flights summary: Get flight information description: Retrieve real-time flight information parameters: - name: flightNumber in: path required: true schema: type: string description: Flight number (e.g., UA1234) example: "UA1234" - name: date in: query schema: type: string format: date description: Flight date (YYYY-MM-DD) example: "2025-06-26" - name: departureAirport in: query schema: type: string description: Departure airport code example: "LAX" - name: arrivalAirport in: query schema: type: string description: Arrival airport code example: "DEN" responses: '200': description: Flight information content: application/json: schema: $ref: '#/components/schemas/FlightInfo' '404': description: Flight not found '500': description: Failed to fetch flight data /flights/{flightNumber}/track: post: tags: - Flights summary: Start flight tracking description: Begin periodic updates for a specific flight parameters: - name: flightNumber in: path required: true schema: type: string description: Flight number requestBody: required: true content: application/json: schema: type: object properties: date: type: string format: date intervalMinutes: type: integer default: 5 required: - date example: date: "2025-06-26" intervalMinutes: 5 responses: '200': description: Flight tracking started content: application/json: schema: type: object properties: message: type: string example: "Started tracking UA1234 on 2025-06-26" delete: tags: - Flights summary: Stop flight tracking description: Stop periodic updates for a specific flight parameters: - name: flightNumber in: path required: true schema: type: string description: Flight number - name: date in: query required: true schema: type: string format: date description: Flight date responses: '200': description: Flight tracking stopped /flights/batch: post: tags: - Flights summary: Get multiple flights information description: Retrieve information for multiple flights at once requestBody: required: true content: application/json: schema: type: object properties: flights: type: array items: type: object properties: flightNumber: type: string date: type: string format: date required: - flightNumber - date example: flights: - flightNumber: "UA1234" date: "2025-06-26" - flightNumber: "AA789" date: "2025-06-26" responses: '200': description: Multiple flight information content: application/json: schema: type: array items: $ref: '#/components/schemas/FlightInfo' /flights/tracking/status: get: tags: - Flights summary: Get flight tracking status description: Get the status of all currently tracked flights responses: '200': description: Flight tracking status content: application/json: schema: type: object properties: trackedFlights: type: array items: type: object properties: flightKey: type: string vipName: type: string lastUpdate: type: string format: date-time status: type: string /admin/authenticate: post: tags: - Admin summary: Admin authentication description: Authenticate admin user requestBody: required: true content: application/json: schema: type: object properties: password: type: string required: - password responses: '200': description: Authentication successful content: application/json: schema: type: object properties: success: type: boolean '401': description: Invalid password /admin/settings: get: tags: - Admin summary: Get admin settings description: Retrieve current admin settings (requires authentication) parameters: - name: admin-auth in: header required: true schema: type: string description: Admin authentication header responses: '200': description: Admin settings content: application/json: schema: $ref: '#/components/schemas/AdminSettings' '401': description: Unauthorized post: tags: - Admin summary: Update admin settings description: Update admin settings (requires authentication) parameters: - name: admin-auth in: header required: true schema: type: string description: Admin authentication header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdminSettings' responses: '200': description: Settings updated successfully '401': description: Unauthorized components: schemas: VIP: type: object properties: id: type: string description: Unique VIP identifier name: type: string description: VIP's full name organization: type: string description: VIP's organization or company transportMode: type: string enum: [flight, self-driving] description: Mode of transportation flights: type: array items: $ref: '#/components/schemas/Flight' description: Flight information (for flight transport mode) expectedArrival: type: string format: date-time description: Expected arrival time (for self-driving mode) needsAirportPickup: type: boolean description: Whether VIP needs airport pickup needsVenueTransport: type: boolean description: Whether VIP needs venue transport assignedDriverIds: type: array items: type: string description: List of assigned driver IDs notes: type: string description: Additional notes about the VIP schedule: type: array items: $ref: '#/components/schemas/ScheduleEvent' description: VIP's schedule (usually empty, fetched separately) VIPCreate: type: object required: - name - organization - transportMode properties: name: type: string minLength: 1 organization: type: string minLength: 1 transportMode: type: string enum: [flight, self-driving] flights: type: array items: $ref: '#/components/schemas/Flight' expectedArrival: type: string format: date-time needsAirportPickup: type: boolean default: true needsVenueTransport: type: boolean default: true notes: type: string Flight: type: object required: - flightNumber - flightDate - segment properties: flightNumber: type: string description: Flight number (e.g., UA1234) flightDate: type: string format: date description: Flight date segment: type: integer minimum: 1 description: Flight segment number for connecting flights validated: type: boolean description: Whether flight has been validated validationData: $ref: '#/components/schemas/FlightInfo' Driver: type: object properties: id: type: string description: Unique driver identifier name: type: string description: Driver's full name phone: type: string description: Driver's phone number currentLocation: $ref: '#/components/schemas/Location' assignedVipIds: type: array items: type: string description: List of assigned VIP IDs DriverCreate: type: object required: - name - phone properties: name: type: string minLength: 1 phone: type: string minLength: 1 currentLocation: $ref: '#/components/schemas/Location' Location: type: object properties: lat: type: number format: float description: Latitude lng: type: number format: float description: Longitude ScheduleEvent: type: object properties: id: type: string description: Unique event identifier title: type: string description: Event title location: type: string description: Event location startTime: type: string format: date-time description: Event start time endTime: type: string format: date-time description: Event end time description: type: string description: Event description assignedDriverId: type: string description: Assigned driver ID status: $ref: '#/components/schemas/EventStatus' type: $ref: '#/components/schemas/EventType' ScheduleEventCreate: type: object required: - title - location - startTime - endTime - type properties: title: type: string minLength: 1 location: type: string minLength: 1 startTime: type: string format: date-time endTime: type: string format: date-time description: type: string type: $ref: '#/components/schemas/EventType' assignedDriverId: type: string EventStatus: type: string enum: [scheduled, in-progress, completed, cancelled] description: Current status of the event EventType: type: string enum: [transport, meeting, event, meal, accommodation] description: Type of event FlightInfo: type: object properties: flightNumber: type: string flightDate: type: string format: date status: type: string enum: [scheduled, active, landed, cancelled, delayed] airline: type: string aircraft: type: string departure: $ref: '#/components/schemas/FlightLocation' arrival: $ref: '#/components/schemas/FlightLocation' delay: type: integer description: Delay in minutes lastUpdated: type: string format: date-time source: type: string description: Data source (e.g., aviationstack) FlightLocation: type: object properties: airport: type: string description: Airport code airportName: type: string description: Full airport name scheduled: type: string format: date-time estimated: type: string format: date-time actual: type: string format: date-time terminal: type: string gate: type: string AdminSettings: type: object properties: apiKeys: type: object properties: aviationStackKey: type: string description: Masked API key googleMapsKey: type: string description: Masked API key twilioKey: type: string description: Masked API key systemSettings: type: object properties: defaultPickupLocation: type: string defaultDropoffLocation: type: string timeZone: type: string notificationsEnabled: type: boolean ValidationError: type: object properties: error: type: string validationErrors: type: array items: $ref: '#/components/schemas/ValidationMessage' warnings: type: array items: $ref: '#/components/schemas/ValidationWarning' message: type: string ValidationMessage: type: object properties: field: type: string message: type: string code: type: string ValidationWarning: type: object properties: field: type: string message: type: string code: type: string securitySchemes: AdminAuth: type: apiKey in: header name: admin-auth description: Admin authentication header security: - AdminAuth: []