API Evangelist conversational phrasing for OPERA Cloud Block Reservation Asynchronous Block Async API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OPERA Cloud Block Reservation Asynchronous Block Async API
  version: 1.0.0
extends: openapi/oracle-hospitality-blockasync-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 21
- target: $.paths['/externalSystems/{extSystemCode}/hotels/{hotelId}/blocks/allocationSummary'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a hotel's block allocation summary
      effect: read
      questions:
      - How can I pull group block allocations, rates and room type stats for a date range?
      - Can I request only blocks changed within a last-modified window?
      - Is there a limit on the date range for a block allocation summary?
      instructions:
      - text: Request the block allocation summary for hotel {hotelId} from {startDate} to {endDate} as system {extSystemCode}.
        slots:
          hotelId: path.hotelId
          startDate: requestBody.startDate
          endDate: requestBody.endDate
          extSystemCode: path.extSystemCode
      - text: Start a block allocation summary for property {hotelId}, system {extSystemCode}, including net rates.
        slots:
          hotelId: path.hotelId
          extSystemCode: path.extSystemCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/externalSystems/{extSystemCode}/hotels/{hotelId}/blocks/allocationSummary/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a completed block allocation summary
      effect: read
      questions:
      - Where do I download the block allocation summary once the job is done?
      - What inventory and rate details come back in a finished block allocation summary?
      instructions:
      - text: Fetch block allocation summary {requestId} for hotel {hotelId} from system {extSystemCode}.
        slots:
          requestId: path.requestId
          hotelId: path.hotelId
          extSystemCode: path.extSystemCode
      - text: Show the allocated blocks returned by summary request {requestId} at property {hotelId}, system {extSystemCode}.
        slots:
          requestId: path.requestId
          hotelId: path.hotelId
          extSystemCode: path.extSystemCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/externalSystems/{extSystemCode}/hotels/{hotelId}/blocks/allocationSummary/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a block allocation summary is ready
      effect: read
      questions:
      - Is my block allocation summary request finished processing?
      - How do I poll a hotel-wide block allocation summary job?
      instructions:
      - text: Check whether block allocation summary {requestId} for hotel {hotelId} from {extSystemCode} is ready.
        slots:
          requestId: path.requestId
          hotelId: path.hotelId
          extSystemCode: path.extSystemCode
      - text: Poll allocation summary request {requestId} at property {hotelId}, system {extSystemCode}.
        slots:
          requestId: path.requestId
          hotelId: path.hotelId
          extSystemCode: path.extSystemCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocation'].post
  update:
    x-apievangelist-phrasing:
      intent: Set room allocations and rates on a block
      effect: write
      questions:
      - How do I add room type allocations and rates to a group block?
      - Can I load a block's room inventory asynchronously?
      instructions:
      - text: Set room type allocations on block {blockId} at hotel {hotelId} using {criteria}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
          criteria: requestBody.criteria
      - text: Add allocated rooms and rates to group block {blockId} at property {hotelId}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocation/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a block allocation update
      effect: read
      questions:
      - Did setting allocations on my block trigger any overbooking warnings?
      - Where do I see the outcome of a block room allocation job?
      instructions:
      - text: Show warnings from allocation job {requestId} on block {blockId} at hotel {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Fetch the overbooking results for block {blockId} allocation request {requestId} at property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocation/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a block allocation update finished
      effect: read
      questions:
      - Is my block room allocation job complete?
      - How can I poll the set-allocation process on a block?
      instructions:
      - text: Check whether allocation job {requestId} on block {blockId} at hotel {hotelId} is done.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll the room allocation request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocationRanges'].post
  update:
    x-apievangelist-phrasing:
      intent: Set block allocations across date ranges
      effect: write
      questions:
      - How do I set a block's allocation for several date ranges and room types at once?
      - Can allocation ranges use a generic room type?
      instructions:
      - text: Set allocation ranges {allocationRanges} on block {blockId} at hotel {hotelId}.
        slots:
          allocationRanges: requestBody.allocationRanges
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Apply date-range allocations for generic room type {genericRoomType} on block {blockId} at property {hotelId}.
        slots:
          genericRoomType: requestBody.genericRoomType
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocationRanges/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a block allocation ranges update
      effect: read
      questions:
      - Were there overbooking warnings from setting date-range allocations on my block?
      - Where can I read the result of an allocation ranges job?
      instructions:
      - text: List overbooking warnings raised when date ranges were applied to block {blockId} at hotel {hotelId}, request {requestId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Fetch date-range allocation results {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/allocationRanges/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a block allocation ranges job finished
      effect: read
      questions:
      - Is the allocation ranges update on my block still running?
      - How do I poll a date-range allocation job for a block?
      instructions:
      - text: Tell me if the multi-date-range allocation request {requestId} for block {blockId}, hotel {hotelId} has completed.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll date-range allocation request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/shift'].post
  update:
    x-apievangelist-phrasing:
      intent: Shift a block's dates
      effect: write
      questions:
      - How do I move a group block to a new start date?
      - Can I shift the dates of an existing business block in OPERA?
      instructions:
      - text: Shift block {blockId} at hotel {hotelId} using {criteria}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
          criteria: requestBody.criteria
      - text: Move group block {blockId} at property {hotelId} to new dates.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/shift/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a block date shift
      effect: read
      questions:
      - Did shifting my block's dates produce any errors or warnings?
      - Where do I see the outcome of a block shift?
      instructions:
      - text: Show errors and warnings from shift job {requestId} on block {blockId} at hotel {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Fetch date-move results {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/shift/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a block date shift finished
      effect: read
      questions:
      - Has my block date shift finished?
      - How can I poll a shift-block process?
      instructions:
      - text: Check whether shift job {requestId} on block {blockId} at hotel {hotelId} is done.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll the date-move request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/recalculateRoomForecast'].post
  update:
    x-apievangelist-phrasing:
      intent: Recalculate a block's forecast room rates
      effect: write
      questions:
      - How do I recalculate forecast room rates on a business block?
      - Can room forecast rates for a group be refreshed after pricing changes?
      instructions:
      - text: Recalculate forecast room rates for block {blockId} at hotel {hotelId}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Start a room forecast recalculation on business block {blockId}, property {hotelId}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/recalculateRoomForecast/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a room forecast recalculation
      effect: read
      questions:
      - Were there errors when recalculating my block's room forecast?
      - Where do I read the outcome of a forecast rate recalculation?
      instructions:
      - text: Show errors and warnings from forecast recalculation {requestId} on block {blockId} at hotel {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Fetch room forecast recalculation results {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/recalculateRoomForecast/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a room forecast recalculation finished
      effect: read
      questions:
      - Is the room forecast recalculation on my block done?
      - How do I poll a forecast rate recalculation job?
      instructions:
      - text: Check whether forecast recalculation {requestId} on block {blockId} at hotel {hotelId} is complete.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll room forecast recalculation request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/refreshProjectedRevenues'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a block's projected revenues
      effect: write
      questions:
      - How can I refresh projected revenue figures on a business block?
      - Is refreshing a group's projected revenues an async job?
      instructions:
      - text: Refresh projected revenues for block {blockId} at hotel {hotelId}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Start a projected revenue refresh on business block {blockId}, property {hotelId}.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/refreshProjectedRevenues/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of a projected revenue refresh
      effect: read
      questions:
      - Did refreshing projected revenues on my block return any errors?
      - Where do I see the outcome of a projected revenues refresh?
      instructions:
      - text: Show errors and warnings from projected revenue refresh {requestId} on block {blockId} at hotel {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Fetch projected revenue refresh results {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/refreshProjectedRevenues/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a projected revenue refresh finished
      effect: read
      questions:
      - Is the projected revenue refresh on my block complete?
      - How can I poll a projected revenues refresh job?
      instructions:
      - text: Check whether projected revenue refresh {requestId} on block {blockId} at hotel {hotelId} is done.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll projected revenue refresh request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a block's details asynchronously
      effect: read
      questions:
      - How do I retrieve a large block by ID without the request timing out?
      - Can I fetch a block's allocated room types for a set number of days?
      - What if I don't know the block ID yet?
      instructions:
      - text: Start fetching block {blockId} at hotel {hotelId} asynchronously.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Request block {blockId} at hotel {hotelId} with allocated room types from {startDate} for {numberOfDays} days.
        slots:
          blockId: path.blockId
          hotelId: path.hotelId
          startDate: query.startDate
          numberOfDays: query.numberOfDays
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/async/{requestId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a block fetched asynchronously
      effect: read
      questions:
      - Where do I pick up the block details from my async fetch request?
      - What block information comes back once the async retrieval completes?
      instructions:
      - text: Get the block details from async fetch {requestId} for block {blockId} at hotel {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Show the retrieved block {blockId} from request {requestId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hotels/{hotelId}/blocks/{blockId}/async/{requestId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if an async block fetch is ready
      effect: read
      questions:
      - Has my asynchronous block retrieval been processed yet?
      - How do I poll an async block fetch request?
      instructions:
      - text: Check whether async block fetch {requestId} for block {blockId} at hotel {hotelId} is ready.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      - text: Poll block retrieval request {requestId} for block {blockId}, property {hotelId}.
        slots:
          requestId: path.requestId
          blockId: path.blockId
          hotelId: path.hotelId
      method: generated
      generated: '2026-09-26'