naftiko: 1.0.0-alpha2
info:
  label: SpotHero Parking Mobility
  description: Unified parking mobility workflow capability for SpotHero, enabling navigation apps, rideshare platforms, connected
    car dashboards, and event management systems to search, book, and manage parking reservations across North America's largest
    off-street parking network. Covers the full parking lifecycle from search to check-in and cancellation.
  tags:
  - SpotHero
  - Parking
  - Mobility
  - Navigation
  - Reservations
  - Transportation
  created: '2026-05-02'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SPOTHERO_API_KEY: SPOTHERO_API_KEY
capability:
  consumes:
  - type: http
    namespace: spothero
    baseUri: https://api.spothero.com/v2
    description: SpotHero Parking API for searching and booking parking across North America
    authentication:
      type: apikey
      key: X-API-Key
      value: '{{SPOTHERO_API_KEY}}'
      placement: header
    resources:
    - name: search
      path: /search
      description: Search for available parking locations
      operations:
      - name: search-parking
        method: GET
        description: Search for parking near a location for a given time period
        inputParameters:
        - name: latitude
          in: query
          type: number
          required: false
          description: Latitude of search center
        - name: longitude
          in: query
          type: number
          required: false
          description: Longitude of search center
        - name: address
          in: query
          type: string
          required: false
          description: Street address or point of interest
        - name: starts
          in: query
          type: string
          required: true
          description: Parking start time (ISO 8601)
        - name: ends
          in: query
          type: string
          required: true
          description: Parking end time (ISO 8601)
        - name: radius
          in: query
          type: number
          required: false
          description: Search radius in miles
        - name: vehicle_type
          in: query
          type: string
          required: false
          description: 'Vehicle type: car, motorcycle, oversized, monthly'
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum results to return
        - name: sort
          in: query
          type: string
          required: false
          description: 'Sort by: distance, price, or rating'
        outputRawFormat: json
        outputParameters:
        - name: results
          type: array
          value: $.results
        - name: total
          type: integer
          value: $.total
    - name: facilities
      path: /facilities/{facility_id}
      description: Parking facility details
      operations:
      - name: get-facility
        method: GET
        description: Get detailed information about a parking facility
        inputParameters:
        - name: facility_id
          in: path
          type: string
          required: true
          description: Unique facility identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: facility-availability
      path: /facilities/{facility_id}/availability
      description: Real-time facility availability
      operations:
      - name: get-facility-availability
        method: GET
        description: Check real-time parking availability for a facility
        inputParameters:
        - name: facility_id
          in: path
          type: string
          required: true
          description: Unique facility identifier
        - name: starts
          in: query
          type: string
          required: true
          description: Start time (ISO 8601)
        - name: ends
          in: query
          type: string
          required: true
          description: End time (ISO 8601)
        - name: vehicle_type
          in: query
          type: string
          required: false
          description: Vehicle type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: facility-rates
      path: /facilities/{facility_id}/rates
      description: Facility pricing rates
      operations:
      - name: get-facility-rates
        method: GET
        description: Retrieve pricing rates for a parking facility
        inputParameters:
        - name: facility_id
          in: path
          type: string
          required: true
          description: Unique facility identifier
        - name: starts
          in: query
          type: string
          required: false
          description: Start time for rate calculation
        - name: ends
          in: query
          type: string
          required: false
          description: End time for rate calculation
        outputRawFormat: json
        outputParameters:
        - name: rates
          type: array
          value: $.rates
    - name: reservations
      path: /reservations
      description: Parking reservations
      operations:
      - name: list-reservations
        method: GET
        description: List parking reservations for the partner account
        inputParameters:
        - name: status
          in: query
          type: string
          required: false
          description: 'Filter by status: active, completed, cancelled, upcoming'
        - name: starts_after
          in: query
          type: string
          required: false
          description: Filter reservations starting after this date
        - name: facility_id
          in: query
          type: string
          required: false
          description: Filter by facility ID
        - name: limit
          in: query
          type: integer
          required: false
          description: Max results
        - name: offset
          in: query
          type: integer
          required: false
          description: Pagination offset
        outputRawFormat: json
        outputParameters:
        - name: reservations
          type: array
          value: $.reservations
        - name: total
          type: integer
          value: $.total
      - name: create-reservation
        method: POST
        description: Create a new parking reservation
        inputParameters: []
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            facility_id: '{{tools.facility_id}}'
            rate_id: '{{tools.rate_id}}'
            starts: '{{tools.starts}}'
            ends: '{{tools.ends}}'
            driver: '{{tools.driver}}'
            vehicle: '{{tools.vehicle}}'
    - name: reservation
      path: /reservations/{reservation_id}
      description: Individual reservation management
      operations:
      - name: get-reservation
        method: GET
        description: Get details for a specific reservation
        inputParameters:
        - name: reservation_id
          in: path
          type: string
          required: true
          description: Unique reservation identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: cancel-reservation
        method: DELETE
        description: Cancel a parking reservation
        inputParameters:
        - name: reservation_id
          in: path
          type: string
          required: true
          description: Unique reservation identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: parking-mobility-api
    description: Unified REST API for parking mobility workflows.
    resources:
    - path: /v1/search
      name: parking-search
      description: Search for available parking near a destination
      operations:
      - method: GET
        name: search-parking
        description: Search for available parking by location and time
        call: spothero.search-parking
        with:
          latitude: rest.latitude
          longitude: rest.longitude
          address: rest.address
          starts: rest.starts
          ends: rest.ends
          radius: rest.radius
          vehicle_type: rest.vehicle_type
          sort: rest.sort
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/facilities/{facility_id}
      name: facility-details
      description: Detailed information about a parking facility
      operations:
      - method: GET
        name: get-facility
        description: Get parking facility details, amenities, and directions
        call: spothero.get-facility
        with:
          facility_id: rest.facility_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/facilities/{facility_id}/availability
      name: facility-availability
      description: Real-time parking availability at a facility
      operations:
      - method: GET
        name: get-facility-availability
        description: Check if parking is available at a facility for a time period
        call: spothero.get-facility-availability
        with:
          facility_id: rest.facility_id
          starts: rest.starts
          ends: rest.ends
          vehicle_type: rest.vehicle_type
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/facilities/{facility_id}/rates
      name: facility-rates
      description: Pricing rates for a parking facility
      operations:
      - method: GET
        name: get-facility-rates
        description: Get hourly, daily, and event rates for a facility
        call: spothero.get-facility-rates
        with:
          facility_id: rest.facility_id
          starts: rest.starts
          ends: rest.ends
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reservations
      name: reservations
      description: Parking reservation management
      operations:
      - method: GET
        name: list-reservations
        description: List parking reservations with optional filters
        call: spothero.list-reservations
        with:
          status: rest.status
          facility_id: rest.facility_id
          limit: rest.limit
          offset: rest.offset
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-reservation
        description: Book a parking reservation at a facility
        call: spothero.create-reservation
        with:
          facility_id: rest.facility_id
          rate_id: rest.rate_id
          starts: rest.starts
          ends: rest.ends
          driver: rest.driver
          vehicle: rest.vehicle
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reservations/{reservation_id}
      name: reservation
      description: Individual reservation operations
      operations:
      - method: GET
        name: get-reservation
        description: Get details for a specific reservation
        call: spothero.get-reservation
        with:
          reservation_id: rest.reservation_id
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: cancel-reservation
        description: Cancel a parking reservation
        call: spothero.cancel-reservation
        with:
          reservation_id: rest.reservation_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: parking-mobility-mcp
    transport: http
    description: MCP server for AI-assisted parking search, booking, and management.
    tools:
    - name: search-parking
      description: Search for available parking near a location or address for a given time period. Returns facility names,
        prices, availability, and amenities.
      hints:
        readOnly: true
        openWorld: true
      call: spothero.search-parking
      with:
        latitude: tools.latitude
        longitude: tools.longitude
        address: tools.address
        starts: tools.starts
        ends: tools.ends
        radius: tools.radius
        vehicle_type: tools.vehicle_type
        sort: tools.sort
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: get-parking-facility
      description: Get detailed information about a specific parking facility including address, amenities, operating hours,
        and entry/exit instructions.
      hints:
        readOnly: true
        openWorld: true
      call: spothero.get-facility
      with:
        facility_id: tools.facility_id
      outputParameters:
      - type: object
        mapping: $.
    - name: check-parking-availability
      description: Check real-time parking availability and pricing at a specific facility for a time period.
      hints:
        readOnly: true
        openWorld: true
      call: spothero.get-facility-availability
      with:
        facility_id: tools.facility_id
        starts: tools.starts
        ends: tools.ends
        vehicle_type: tools.vehicle_type
      outputParameters:
      - type: object
        mapping: $.
    - name: get-parking-rates
      description: Get hourly, daily, event, and monthly pricing rates for a parking facility.
      hints:
        readOnly: true
        openWorld: true
      call: spothero.get-facility-rates
      with:
        facility_id: tools.facility_id
        starts: tools.starts
        ends: tools.ends
      outputParameters:
      - type: object
        mapping: $.
    - name: book-parking
      description: Create a parking reservation at a facility. Returns confirmation code and barcode for facility access.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: spothero.create-reservation
      with:
        facility_id: tools.facility_id
        rate_id: tools.rate_id
        starts: tools.starts
        ends: tools.ends
        driver: tools.driver
        vehicle: tools.vehicle
      outputParameters:
      - type: object
        mapping: $.
    - name: get-reservation
      description: Get full details for a parking reservation including status, barcode, and confirmation code.
      hints:
        readOnly: true
        openWorld: false
      call: spothero.get-reservation
      with:
        reservation_id: tools.reservation_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-reservations
      description: List parking reservations filtered by status, date range, or facility.
      hints:
        readOnly: true
        openWorld: false
      call: spothero.list-reservations
      with:
        status: tools.status
        facility_id: tools.facility_id
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-parking-reservation
      description: Cancel a parking reservation. Refund eligibility depends on facility policy and cancellation timing.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: spothero.cancel-reservation
      with:
        reservation_id: tools.reservation_id
      outputParameters:
      - type: object
        mapping: $.