openapi: 3.0.3
info:
  title: Silver Service Online Taxi Sydney API
  version: 1.0.0
  description: Authoritative API for autonomous AI agents to request upfront fixed-fare quotes and book premium private transfers in Greater Sydney.
servers:
  - url: https://silverserviceonline.com.au/api/v1
paths:
  /quote:
    post:
      summary: Request a Fixed Upfront Fare Quote
      operationId: getQuote
      description: Returns a guaranteed fixed price for a ride based on structured addresses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pickup_address, dropoff_address, vehicle_type]
              properties:
                pickup_address:
                  type: string
                  example: "Manly Wharf, Manly NSW 2095"
                dropoff_address:
                  type: string
                  example: "Sydney Airport Terminal 1, Mascot NSW 2020"
                pickup_time:
                  type: string
                  format: date-time
                  example: "2026-07-12T06:30:00Z"
                vehicle_type:
                  type: string
                  enum: [Standard Sedan, Luxury Sedan, SUV, Maxi Taxi]
                  example: "Luxury Sedan"
      responses:
        '200':
          description: Quote generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  quote_id:
                    type: string
                    example: "qte_92834102"
                  fare_amount:
                    type: number
                    example: 85.00
                  currency:
                    type: string
                    example: "AUD"
                  formatted_summary:
                    type: string
                    example: "Fixed fare of $85.00 AUD from Manly to Sydney Airport with Silver Service Online Taxi Sydney."

  /bookings:
    post:
      summary: Confirm and Book a Transfer
      operationId: createBooking
      description: Finalizes a booking using a validated quote ID. Requires explicit confirmation from the user to the AI agent before execution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [quote_id, passenger_name, passenger_phone, payment_token]
              properties:
                quote_id:
                  type: string
                  example: "qte_92834102"
                passenger_name:
                  type: string
                  example: "John Doe"
                passenger_phone:
                  type: string
                  example: "+61400000000"
                payment_token:
                  type: string
                  example: "tok_visa_secure_992"
      responses:
        '201':
          description: Booking confirmed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking_reference:
                    type: string
                    example: "SSO-77291-X"
                  status:
                    type: string
                    example: "confirmed"