arazzo: 1.0.1
info:
  title: StayingAPI — check availability, then price the stay
  summary: Confirm a listing is bookable for a date window, then get a real quote and its reviews.
  description: >-
    A three-step read flow against one known listing: day-by-day availability over the
    window, a real price quote for the same dates and occupancy, then normalized reviews.
    Useful as the backing flow for a price-drop watcher or an availability alert. Includes a
    zero-credit balance check first so an agent knows whether it can afford the work.
  version: 1.0.0
sourceDescriptions:
  - name: stayingapi
    url: ../openapi/stayingapi-openapi-original.json
    type: openapi
workflows:
  - workflowId: availability-then-price
    summary: Balance check, availability window, price quote, and reviews for one listing.
    inputs:
      type: object
      required:
        - platform
        - listingId
        - checkIn
        - checkOut
      properties:
        platform:
          type: string
          description: airbnb | booking | vrbo | google
        listingId:
          type: string
          description: >-
            Platform-native id — numeric on Airbnb/Vrbo, a slug on Booking.com/Google. A bare
            Booking.com slug needs a country (see error code needs_country).
        checkIn:
          type: string
          description: YYYY-MM-DD
        checkOut:
          type: string
          description: YYYY-MM-DD
        adults:
          type: integer
          default: 2
    steps:
      - stepId: checkBalance
        description: Read plan, spendable credits and rate limit. Always 0 credits.
        operationId: account
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          available: $response.body#/data/credits/available
          env: $response.body#/data/key/env
          rpm: $response.body#/data/rateLimit/requestsPerMinute
      - stepId: checkAvailability
        description: Day-by-day availability for the listing across the requested window.
        operationId: availability
        parameters:
          - name: platform
            in: query
            value: $inputs.platform
          - name: listingId
            in: query
            value: $inputs.listingId
          - name: startDate
            in: query
            value: $inputs.checkIn
          - name: endDate
            in: query
            value: $inputs.checkOut
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          dates: $response.body#/data/0/dates
      - stepId: getPrice
        description: A real quote for the same listing, dates and occupancy.
        operationId: price
        parameters:
          - name: platform
            in: query
            value: $inputs.platform
          - name: listingId
            in: query
            value: $inputs.listingId
          - name: checkIn
            in: query
            value: $inputs.checkIn
          - name: checkOut
            in: query
            value: $inputs.checkOut
          - name: adults
            in: query
            value: $inputs.adults
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          totalPrice: $response.body#/data/totalPrice
          nightlyPrice: $response.body#/data/nightlyPrice
          currency: $response.body#/data/currency
          bookingUrl: $response.body#/data/url
      - stepId: getReviews
        description: Normalized reviews for the same listing, first page.
        operationId: reviews
        parameters:
          - name: platform
            in: query
            value: $inputs.platform
          - name: listingId
            in: query
            value: $inputs.listingId
          - name: limit
            in: query
            value: 20
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          reviews: $response.body#/data
          nextCursor: $response.body#/meta/pagination/nextCursor
    outputs:
      creditsAvailable: $steps.checkBalance.outputs.available
      availability: $steps.checkAvailability.outputs.dates
      totalPrice: $steps.getPrice.outputs.totalPrice
      currency: $steps.getPrice.outputs.currency
      bookingUrl: $steps.getPrice.outputs.bookingUrl
      reviews: $steps.getReviews.outputs.reviews
x-apievangelist:
  generated: '2026-08-09'
  method: generated
  source: openapi/stayingapi-openapi-original.json
  note: >-
    operationIds account, availability, price and reviews verified verbatim in the harvested
    spec. Run with a stay_test_ key for synchronous 200s; a live key may answer 202 + jobId
    on the availability, price and reviews steps.