openapi.yaml

openapi: 3.1.0
info:
  title: RailForLess API
  description: The API that powers RailForless.US!
  version: 1.0.0

servers:
  - url: https://api.railforless.us
    description: Production

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key required for authentication. Email info@railforless.us to obtain an API key.

security:
  - ApiKeyAuth: []

paths:
  /fares:
    get:
      summary: Search for Amtrak fares
      description: Fetches available Amtrak fares based on origin, destination, and date range.
      operationId: searchFares
      parameters:
        - name: origin
          in: query
          required: true
          description: The starting station code.
          schema:
            type: string
            example: "NYP"
        - name: destination
          in: query
          required: true
          description: The destination station code.
          schema:
            type: string
            example: "MTR"
        - name: startDate
          in: query
          required: true
          description: The earliest departure date for the search, inclusive.
          schema:
            type: string
            format: date
            example: "2025-10-11"
        - name: endDate
          in: query
          required: true
          description: The latest departure date for the search, inclusive.
          schema:
            type: string
            format: date
            example: "2025-10-20"
        - name: accessible
          in: query
          required: false
          description: Whether to ONLY include accessible fares. This will override the bedroom and family options.
          schema:
            type: boolean
            example: true
        - name: roundTrip
          in: query
          required: false
          description: Specify if the search should include the opposite direction as well.
          schema:
            type: boolean
            example: true
        - name: bedrooms
          in: query
          required: false
          description: Specify if bedroom accommodations should be included in the search results. This will increase API response time by 100% or more.
          schema:
            type: boolean
            example: true
        - name: familyRooms
          in: query
          required: false
          description: Specify if family room accommodations should be included in the search results. This will increase API response time by 100% or more.
          schema:
            type: boolean
            example: true
      responses:
        '200':
          description: Successful response with a list of available fares.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    departureDate:
                      type: string
                      format: date-time
                      description: The specific date of this departure option.
                    origin:
                      type: string
                      description: The origin station code for this leg of the journey.
                    destination:
                      type: string
                      description: The destination station code for this leg of the journey.
                    options:
                      type: array
                      items:
                        type: object
                        properties:
                          departureDateTime:
                            type: string
                            format: date-time
                          arrivalDateTime:
                            type: string
                            format: date-time
                          elapsedSeconds:
                            type: integer
                            description: Total travel time in seconds.
                          accommodations:
                            type: array
                            items:
                              type: object
                              properties:
                                class:
                                  type: string
                                  example: "Coach"
                                fareFamily:
                                  type: string
                                  example: "VLU"
                                legAccommodations:
                                  type: array
                                  description: A nested array representing accommodations per leg.
                                  items:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        fare:
                                          type: object
                                          properties:
                                            accommodation:
                                              type: number
                                              format: float
                                            rail:
                                              type: number
                                              format: float
                                            total:
                                              type: number
                                              format: float
                                        availableInventory:
                                          type: integer
                                        rbd:
                                          type: string
                                          description: Reservation Booking Designator.
                                          example: "YB"
                                        name:
                                          type: string
                                          example: "Coach Seat"
                                        roomType:
                                          type: string
                                          example: "Other"
                                        isAdditionalProduct:
                                          type: boolean
                          travelLegs:
                            type: array
                            items:
                              type: object
                              properties:
                                trainId:
                                  type: string
                                  example: "69"
                                route:
                                  type: string
                                  example: "Adirondack"
                                origin:
                                  type: string
                                  example: "NYP"
                                departureDateTime:
                                  type: string
                                  format: date-time
                                destination:
                                  type: string
                                  example: "MTR"
                                arrivalDateTime:
                                  type: string
                                  format: date-time
                                elapsedSeconds:
                                  type: integer
                                type:
                                  type: string
                                  example: "TRAIN"
                                isBorderCross:
                                  type: boolean
                                isSelfTransfer:
                                  type: boolean
                                amenities:
                                  type: array
                                  items:
                                    type: string
                                  example: ["Cafe", "Free WiFi"]
                                addItems:
                                  type: array
                                  items: {}
              examples:
                successful_search:
                  summary: "Successful fare search"
                  description: "Example response when results are found"
                  value:
                    - departureDate: "2025-10-12T07:15:00"
                      origin: "NYP"
                      destination: "MTR"
                      options:
                        - departureDateTime: "2025-10-12T07:15:00"
                          arrivalDateTime: "2025-10-12T20:16:00"
                          elapsedSeconds: 46860
                          accommodations:
                            - class: "Coach"
                              fareFamily: "VLU"
                              legAccommodations:
                                - - fare:
                                      accommodation: 0
                                      rail: 112
                                      total: 112
                                    availableInventory: 43
                                    rbd: "YB"
                                    name: "Coach Seat"
                                    roomType: "Other"
                                    isAdditionalProduct: false
                          travelLegs:
                            - trainId: "69"
                              route: "Adirondack"
                              origin: "NYP"
                              departureDateTime: "2025-10-12T07:15:00"
                              destination: "MTR"
                              arrivalDateTime: "2025-10-12T20:16:00"
                              elapsedSeconds: 46860
                              type: "TRAIN"
                              isBorderCross: true
                              isSelfTransfer: false
                              amenities: ["Cafe", "Free WiFi"]
                              addItems: []
                amtrak_error:
                  summary: "Amtrak error response"
                  description: "Example response when Amtrak cannot complete the search, such as when a route is sold out"
                  value:
                    error:
                      message: "SOLD OUT"
        '400':
          description: Bad Request - The request parameters were invalid.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: Error code identifying the type of validation error
                    message:
                      type: string
                      description: Human-readable error message
                    path:
                      type: array
                      items:
                        type: string
                      description: Array indicating which field(s) caused the error
                  required:
                    - code
                    - message
                    - path
              example:
                - code: "custom"
                  message: "Invalid origin"
                  path:
                    - "origin"
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                        description: Description of the internal server error
                    required:
                      - message
                required:
                  - error
              example:
                error:
                  message: "Example Unrecoverable Error"