Beyond Pricing Public API

openapi: 3.1.1
info:
  title: Beyond Pricing Public API
  version: 2.0.0
  description: Bearer-protected API for third-party integrations. Supports OAuth2
    client credentials and personal access tokens. Follows JSON:API specification.
paths:
  /api/v1/compsets/:
    get:
      operationId: list_compsets
      description: |-
        List the comp sets visible to the authenticated client.

        **Required scope:** `compsets:read`

        **Pagination:** `page[number]` and `page[size]`.

        **Filtering:** `filter[owner]=<user_id>`, `filter[listing]=<id>`,
        `filter[kind]=custom|connected`. `filter[owner]` is only meaningful for
        full-access partner tokens; user-scoped tokens already see one user.

        **Sorting:** `sort=created-at` (default `-created-at`) or `sort=title`;
        prefix with `-` for descending.

        **Compound documents (sideloading):** Use the `include` query parameter
        to embed related resources (JSON:API compound documents). Supported:
        - `owner` - the user who owns the comp set
        - `listing` - the Beyond listing the comp set is anchored to (`null` for
          `custom` comp sets)

        **Example:** `GET /api/v1/compsets/?include=owner,listing`

        Each entry is a lightweight summary (counts, title, `kind`, timestamps).
        Fetch `GET /compsets/{id}/` for the full enriched comp set.
      summary: List comp sets
      parameters:
      - name: sort
        required: false
        in: query
        description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)'
        schema:
          type: array
          items:
            type: string
            enum:
            - created-at
            - -created-at
            - title
            - -title
        explode: false
      - in: query
        name: filter[owner]
        schema:
          type: number
      - in: query
        name: filter[listing]
        schema:
          type: number
      - in: query
        name: filter[kind]
        schema:
          type: string
          enum:
          - connected
          - custom
        description: |-
          * `custom` - Custom
          * `connected` - Connected
      - name: page[number]
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page[size]
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: include
        schema:
          type: array
          items:
            type: string
            enum:
            - owner
            - listing
        description: include query parameter to allow the client to customize which
          related resources should be returned.
        explode: false
      - in: query
        name: fields[compsets]
        schema:
          type: array
          items:
            type: string
            enum:
            - listing-id
            - kind
            - title
            - member-count
            - created-at
            - updated-at
            - owner
            - listing
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Compsets
      security:
      - oauth2:
        - compsets:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PaginatedCompsetSummaryList'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/compsets/{compset_id}/:
    get:
      operationId: get_compset
      description: |-
        Return one comp set by id, fully enriched.

        **Required scope:** `compsets:read`

        Returns the comp set with members enriched across Airbnb, Vrbo, and
        Booking.com, the comp set's headline metrics over the next 30 and 90
        days, and a `performance` block comparing the listing to the aggregated
        compset benchmark over `start_date`..`end_date` (defaults: today →
        today+90d, max range 180 days).

        The `kind` field distinguishes `custom` and `connected` comp sets; for
        `custom` comp sets some `source` fields and the main-listing
        performance metrics are `null`.

        Returns **404** when no comp set with that id is visible to the client.
      summary: Get a comp set by id
      parameters:
      - in: path
        name: compset_id
        schema:
          type: integer
        required: true
      - in: query
        name: start_date
        schema:
          type: string
        description: First stay date (YYYY-MM-DD) for the performance comparison.
          Defaults to today.
      - in: query
        name: end_date
        schema:
          type: string
        description: Last stay date (YYYY-MM-DD) for the performance comparison. Defaults
          to today + 90 days. Range must not exceed 180 days.
      - in: query
        name: fields[compsets]
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - listing-id
            - kind
            - title
            - matched-airbnb-id
            - created-at
            - updated-at
            - source
            - members
            - performance
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Compsets
      security:
      - oauth2:
        - compsets:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CompsetResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/:
    get:
      operationId: list_listings
      description: |-
        Retrieve a paginated list of all listings for the authenticated application.

        **Required scope:** `listings:read`

        **Pagination:** Use `page[number]` and `page[size]` query parameters.

        **Sorting:** Use `sort` query parameter with field names.
        Prefix with `-` for descending order.

        **Filtering:** Use `filter[field]` query parameters.

        **Compound documents:** Use `include` query parameter to include related resources.
      summary: List all listings
      parameters:
      - name: sort
        required: false
        in: query
        description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)'
        schema:
          type: array
          items:
            type: string
            enum:
            - created-at
            - -created-at
            - title
            - -title
            - city
            - -city
        explode: false
      - in: query
        name: filter[owner]
        schema:
          type: number
      - in: query
        name: filter[enabled]
        schema:
          type: boolean
      - name: page[number]
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page[size]
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: include
        schema:
          type: array
          items:
            type: string
            enum:
            - owner
        description: include query parameter to allow the client to customize which
          related resources should be returned.
        explode: false
      - in: query
        name: fields[listings]
        schema:
          type: array
          items:
            type: string
            enum:
            - title
            - image
            - neighborhood
            - city
            - state
            - country
            - room-type
            - bedrooms
            - bathrooms
            - base-price
            - base-price-updated-at
            - min-price
            - min-price-updated-at
            - max-price
            - min-stay
            - extra-guest-fee
            - extra-guest-threshold
            - latitude
            - longitude
            - timezone
            - currency
            - in-active-market
            - enabled
            - address
            - created-at
            - owner
            - channel-listings
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Listings
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PaginatedListingList'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/:
    get:
      operationId: get_listing
      description: |-
        Retrieve detailed information about a specific listing.

        **Required scope:** `listings:read`

        **Compound documents (sideloading):**
        Use the `include` query parameter to include related resources in a single request.
        This follows the JSON:API specification for compound documents.

        Supported includes:
        - `owner` - The user who owns the listing

        **Example:** `GET /api/v1/listings/123/?include=owner`
      summary: Retrieve a listing by ID
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: include
        schema:
          type: array
          items:
            type: string
            enum:
            - owner
        description: include query parameter to allow the client to customize which
          related resources should be returned.
        explode: false
      - in: query
        name: fields[listings]
        schema:
          type: array
          items:
            type: string
            enum:
            - title
            - image
            - neighborhood
            - city
            - state
            - country
            - room-type
            - bedrooms
            - bathrooms
            - base-price
            - base-price-updated-at
            - min-price
            - min-price-updated-at
            - max-price
            - min-stay
            - extra-guest-fee
            - extra-guest-threshold
            - latitude
            - longitude
            - timezone
            - currency
            - in-active-market
            - enabled
            - address
            - created-at
            - owner
            - channel-listings
            - sync-status
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Listings
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListingDetailResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/activation/:
    patch:
      operationId: patch_listing_activation
      description: Enable or disable price syncing for a listing.
      summary: Update listing activation
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Listings
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedListingActivationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListingActivationResponse'
          description: ''
        '304':
          description: Not modified
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/calendar/:
    get:
      operationId: list_listing_calendar
      description: |-
        Retrieve the pricing calendar for a specific listing.

        **Required scope:** `reservations:read`

        **Currency:** Price fields are returned in the owning user's configured
        currency.

        **Date range:** Use `filter[start-date]` and `filter[end-date]` query parameters
        (YYYY-MM-DD, JSON:API spec). Defaults to today through today + 365 days.

        **Sorting:** Use `sort=date` (ascending, default) or `sort=-date`.

        **Pagination:** Use `page[number]` and `page[size]` query parameters.

        **Sparse fieldsets:** Use `fields[calendar-entries]` to select specific fields.

        **Example:** `GET /api/v1/listings/123/calendar/?filter[start-date]=2026-01-01&filter[end-date]=2026-06-30&sort=date`
      summary: Get calendar for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - name: page[number]
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page[size]
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: filter[start-date]
        schema:
          type: string
          format: date
        description: Start date (YYYY-MM-DD). Defaults to today in the listing's timezone.
      - in: query
        name: filter[end-date]
        schema:
          type: string
          format: date
        description: End date (YYYY-MM-DD). Defaults to today + 365 days.
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - -date
          - date
        description: 'Sort calendar entries by date. Supported values: date, -date.
          Defaults to date.'
      - in: query
        name: fields[calendar-entries]
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - date
            - availability
            - price
            - price-posted
            - effective-min-price
            - effective-max-price
            - factors
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Listings
      security:
      - oauth2:
        - reservations:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PaginatedCalendarEntryList'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable - invalid dates or insufficient data
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/:
    get:
      operationId: get_listing_all_customizations
      description: Retrieve every supported customization for a listing.
      summary: Get all customizations for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[listing-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - base-price
            - extra-guest-fees
            - min-max-prices
            - min-stays
            - time-based-adjustments
            - id
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListingCustomizationsResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/base-price/:
    get:
      operationId: get_listing_base_price_customization
      description: Retrieve base price customization for a listing.
      summary: Get base price customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[base-price-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - base-price
            - id
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/BasePriceCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_base_price_customization
      description: Update base price customization for a listing.
      summary: Update base price customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedBasePriceCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/BasePriceCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/extra-guest-fees/:
    get:
      operationId: get_listing_extra_guest_fee_customization
      description: Retrieve extra guest fee customization for a listing.
      summary: Get extra guest fee customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[extra-guest-fee-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - extra-guest-fee
            - extra-guest-threshold
            - id
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ExtraGuestFeeCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_extra_guest_fee_customization
      description: Update extra guest fee customization for a listing.
      summary: Update extra guest fee customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedExtraGuestFeeCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ExtraGuestFeeCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/min-max-prices/:
    get:
      operationId: get_listing_min_max_prices_customization
      description: Retrieve min/max prices customization for a listing.
      summary: Get min/max prices customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[min-max-price-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - min-price
            - max-price
            - monthly-min-price
            - day-of-week-min-prices
            - seasonal-day-of-week-min-prices
            - seasonal-prices
            - seasonal-monthly-prices
            - id
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinMaxPricesCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_min_max_prices_customization
      description: Update min/max prices customization for a listing.
      summary: Update min/max prices customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedMinMaxPricesCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinMaxPricesCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/min-stays/:
    get:
      operationId: get_listing_min_stays_customization
      description: Retrieve min-stays customization for a listing.
      summary: Get min-stays customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[min-stay-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - min-stay
            - gap-fill-min-stay
            - seasonal-min-stays
            - last-minute-min-stays
            - day-of-week-min-stays
            - seasonal-day-of-week-min-stays
            - seasonal-gap-fill-min-stays
            - seasonal-time-based-min-stays
            - id
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinStaysCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_min_stays_customization
      description: Update min-stays customization for a listing.
      summary: Update min-stays customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedMinStaysCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/MinStaysCustomizationResponse'
          description: ''
        '400':
          description: Validation error
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '422':
          description: Unprocessable entity
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
  /api/v1/listings/{listing_id}/customizations/time-based-adjustments/:
    get:
      operationId: get_listing_time_based_adjustments_customization
      description: Retrieve time-based adjustments customization for a listing.
      summary: Get time-based adjustments customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      - in: query
        name: fields[time-based-adjustment-customizations]
        schema:
          type: array
          items:
            type: string
            enum:
            - time-based-adjustments
            - seasonal-time-based-adjustments
            - id
            - dynamic-time-based-adjustments
        description: endpoint return only specific fields in the response on a per-type
          basis by including a fields[TYPE] query parameter.
        explode: false
      tags:
      - Customizations
      security:
      - oauth2:
        - listings:read
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TimeBasedAdjustmentsCustomizationResponse'
          description: ''
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden
        '404':
          description: Not found - resource does not exist
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
    patch:
      operationId: patch_listing_time_based_adjustments_customization
      description: Update time-based adjustments customization for a listing.
      summary: Update time-based adjustments customization for a listing
      parameters:
      - in: path
        name: listing_id
        schema:
          type: integer
        required: true
      tags:
      - Customizations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/PatchedTimeBasedAdjustmentsCustomizationRequest'
        required: true
      security:
      - oauth2:
        - listings:write
      - personalAccessToken: []
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TimeBasedAdjustmentsCustomizationResponse'
          description: ''
        '400'

# --- truncated at 32 KB (237 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beyond-pricing/refs/heads/main/openapi/beyond-pricing-openapi-original.yml