openapi: 3.1.1
info:
  title: Beyond Pricing Public Accounts Compsets 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.
tags:
- name: Compsets
paths:
  /api/v1/compsets/:
    get:
      operationId: list_compsets
      description: "List the comp sets visible to the authenticated client.\n\n**Required scope:** `compsets:read`\n\n**Pagination:** `page[number]` and `page[size]`.\n\n**Filtering:** `filter[owner]=<user_id>`, `filter[listing]=<id>`,\n`filter[kind]=custom|connected`. `filter[owner]` is only meaningful for\nfull-access partner tokens; user-scoped tokens already see one user.\n\n**Sorting:** `sort=created-at` (default `-created-at`) or `sort=title`;\nprefix with `-` for descending.\n\n**Compound documents (sideloading):** Use the `include` query parameter\nto embed related resources (JSON:API compound documents). Supported:\n- `owner` - the user who owns the comp set\n- `listing` - the Beyond listing the comp set is anchored to (`null` for\n  `custom` comp sets)\n\n**Example:** `GET /api/v1/compsets/?include=owner,listing`\n\nEach entry is a lightweight summary (counts, title, `kind`, timestamps).\nFetch `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
components:
  schemas:
    PaginatedCompsetSummaryList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CompsetSummary'
        links:
          type: object
          description: Pagination links for the primary data. These keys MUST be used for pagination links; each MUST be omitted or `null` when that link is unavailable. Values follow JSON:API link rules (URI string, link object, or null). https://jsonapi.org/format/#fetching-pagination https://jsonapi.org/format/#document-links
          properties:
            first:
              type:
              - string
              - 'null'
              format: uri
              example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=1
              description: 'The first page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
            last:
              type:
              - string
              - 'null'
              format: uri
              example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=9
              description: 'The last page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
            prev:
              type:
              - string
              - 'null'
              format: uri
              example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=1
              description: 'The previous page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
            next:
              type:
              - string
              - 'null'
              format: uri
              example: http://example.com/articles?page%5Bsize%5D=10&page%5Bnumber%5D=3
              description: 'The next page of data. A JSON:API link: URI string, link object, or null. See https://jsonapi.org/format/#document-links.'
          additionalProperties: false
        meta:
          type: object
          description: Non-standard meta-information. Page-number stacks often nest totals under `pagination`. JSON:API does not define these keys. Servers MAY add other `meta` members; this schema documents the usual djangorestframework-json-api shape only. https://jsonapi.org/format/#document-meta
          properties:
            pagination:
              type: object
              description: Typical page-number metadata from djangorestframework-json-api; not mandated by JSON:API.
              properties:
                count:
                  type: integer
                  minimum: 0
                  example: 42
                  description: Total number of resources across all pages.
                page:
                  type: integer
                  minimum: 1
                  example: 2
                  description: Current page number (1-based).
                pages:
                  type: integer
                  minimum: 0
                  example: 5
                  description: Total number of pages.
              additionalProperties: false
          additionalProperties: false
      required:
      - data
    Compset:
      type: object
      required:
      - type
      - id
      additionalProperties: false
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/TypeF0bEnum'
          description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
        id: {}
        attributes:
          type: object
          properties:
            listing-id:
              type:
              - integer
              - 'null'
              description: Beyond listing id the comp set is anchored to (null for custom).
            kind:
              enum:
              - custom
              - connected
              type: string
              description: 'Comp set kind: `custom` (no Beyond listing) or `connected` (anchored to a Beyond listing). Custom comp sets have null `source.min-stay`/`base-price`/`health-score`/`market` and a null `performance.main-listing-metrics`.


                * `custom` - Custom

                * `connected` - Connected'
            title:
              type:
              - string
              - 'null'
              description: Comp set title.
            matched-airbnb-id:
              type:
              - string
              - 'null'
              description: Airbnb id Beyond matched to the base listing, when available.
            created-at:
              type:
              - string
              - 'null'
              format: date-time
              description: When the comp set was created.
            updated-at:
              type:
              - string
              - 'null'
              format: date-time
              description: When the comp set was last updated.
            source:
              $ref: '#/components/schemas/CompsetSource'
            members:
              type: array
              items:
                $ref: '#/components/schemas/CompsetMember'
            performance:
              allOf:
              - $ref: '#/components/schemas/CompsetPerformance'
              description: The listing's metrics vs. the aggregated compset benchmark over `start_date`..`end_date`.
          required:
          - kind
          - source
          - members
          - performance
    CompsetSourceMetrics:
      type: object
      description: Headline metrics for the base listing over the next 30 and 90 days.
      properties:
        thirty-day-price:
          type:
          - number
          - 'null'
          format: double
          description: Average posted nightly rate, next 30 days.
        ninety-day-price:
          type:
          - number
          - 'null'
          format: double
          description: Average posted nightly rate, next 90 days.
        thirty-day-adr:
          type:
          - number
          - 'null'
          format: double
          description: Average booked rate (ADR), next 30 days.
        ninety-day-adr:
          type:
          - number
          - 'null'
          format: double
          description: Average booked rate (ADR), next 90 days.
        thirty-day-booked:
          type:
          - number
          - 'null'
          format: double
          description: Occupancy percentage, next 30 days.
        ninety-day-booked:
          type:
          - number
          - 'null'
          format: double
          description: Occupancy percentage, next 90 days.
        thirty-day-availability:
          type:
          - number
          - 'null'
          format: double
          description: Availability percentage, next 30 days.
        ninety-day-availability:
          type:
          - number
          - 'null'
          format: double
          description: Availability percentage, next 90 days.
        thirty-day-min-stays:
          type:
          - integer
          - 'null'
          description: Minimum stay, next 30 days.
        ninety-day-min-stays:
          type:
          - integer
          - 'null'
          description: Minimum stay, next 90 days.
        rating:
          type:
          - number
          - 'null'
          format: double
          description: Aggregate guest star rating.
        reviews-count:
          type:
          - integer
          - 'null'
          description: Number of guest reviews.
        average-service-fee:
          type:
          - number
          - 'null'
          format: double
          description: Average service fee (Airbnb-only; null on other channels).
    CompsetPerformanceAggregateMetrics:
      type: object
      description: The aggregated compset benchmark over the requested date range.
      properties:
        average-posted-rate:
          type:
          - number
          - 'null'
          format: double
          description: Compset average posted nightly rate.
        occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Compset average occupancy percentage.
        average-min-stay:
          type:
          - number
          - 'null'
          format: double
          description: Compset average minimum stay.
        average-booked-rate:
          type:
          - number
          - 'null'
          format: double
          description: Compset average booked rate (ADR).
        adj-occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Compset average adjusted occupancy percentage.
        number-of-nearby-listings:
          type:
          - integer
          - 'null'
          description: Number of members contributing to the aggregate.
    CompsetMemberMetrics:
      type: object
      description: Metrics for a single comp-set member over the next 30 and 90 days.
      properties:
        thirty-day-adr:
          type:
          - number
          - 'null'
          format: double
          description: Average booked rate (ADR), next 30 days.
        ninety-day-adr:
          type:
          - number
          - 'null'
          format: double
          description: Average booked rate (ADR), next 90 days.
        thirty-day-booked:
          type:
          - number
          - 'null'
          format: double
          description: Occupancy percentage, next 30 days.
        ninety-day-booked:
          type:
          - number
          - 'null'
          format: double
          description: Occupancy percentage, next 90 days.
        thirty-day-availability:
          type:
          - number
          - 'null'
          format: double
          description: Availability percentage, next 30 days.
        ninety-day-availability:
          type:
          - number
          - 'null'
          format: double
          description: Availability percentage, next 90 days.
        thirty-day-min-stays:
          type:
          - integer
          - 'null'
          description: Minimum stay, next 30 days.
        ninety-day-min-stays:
          type:
          - integer
          - 'null'
          description: Minimum stay, next 90 days.
        thirty-day-adj-occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Adjusted occupancy percentage, next 30 days.
        ninety-day-adj-occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Adjusted occupancy percentage, next 90 days.
        thirty-day-booked-rate:
          type:
          - number
          - 'null'
          format: double
          description: Booked rate, next 30 days.
        ninety-day-booked-rate:
          type:
          - number
          - 'null'
          format: double
          description: Booked rate, next 90 days.
        base-price:
          type:
          - number
          - 'null'
          format: double
          description: Average base price over the next 365 days.
        currency:
          type:
          - string
          - 'null'
          description: ISO currency code for the member's prices.
        rating:
          type:
          - number
          - 'null'
          format: double
          description: Aggregate guest star rating.
        reviews-count:
          type:
          - integer
          - 'null'
          description: Number of guest reviews.
        average-service-fee:
          type:
          - number
          - 'null'
          format: double
          description: Average service fee (Airbnb-only; null on other channels).
    CompsetPerformanceListingMetrics:
      type: object
      description: The base listing's metrics over the requested date range.
      properties:
        average-posted-rate:
          type:
          - number
          - 'null'
          format: double
          description: Average posted nightly rate over the range.
        occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Occupancy percentage over the range.
        average-min-stay:
          type:
          - number
          - 'null'
          format: double
          description: Average minimum stay over the range.
        average-booked-rate:
          type:
          - number
          - 'null'
          format: double
          description: Average booked rate (ADR) over the range.
        adj-occupancy:
          type:
          - number
          - 'null'
          format: double
          description: Adjusted occupancy percentage over the range.
    CompsetPerformance:
      type: object
      description: Date-ranged comparison of the base listing vs. the compset benchmark.
      properties:
        start-date:
          type: string
          format: date
          description: First stay date in the range.
        end-date:
          type: string
          format: date
          description: Last stay date in the range.
        currency:
          type: string
          description: ISO currency code for the figures.
        main-listing-metrics:
          oneOf:
          - $ref: '#/components/schemas/CompsetPerformanceListingMetrics'
          - type: 'null'
          description: The base listing's metrics over the range. `null` for `custom` comp sets, which have no Beyond listing.
        aggregated-metrics:
          $ref: '#/components/schemas/CompsetPerformanceAggregateMetrics'
      required:
      - aggregated-metrics
      - currency
      - end-date
      - start-date
    TypeF0bEnum:
      type: string
      enum:
      - compsets
    CompsetResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Compset'
      required:
      - data
    CompsetSummary:
      type: object
      required:
      - type
      - id
      additionalProperties: false
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/TypeF0bEnum'
          description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
        id:
          type: integer
        attributes:
          type: object
          properties:
            listing-id:
              type:
              - integer
              - 'null'
              readOnly: true
              description: Beyond listing id the comp set is anchored to (null for custom).
            kind:
              enum:
              - custom
              - connected
              type: string
              description: 'Comp set kind: `custom` or `connected`.'
              readOnly: true
            title:
              type:
              - string
              - 'null'
              readOnly: true
              description: Comp set name.
            member-count:
              type: integer
              readOnly: true
              description: Total number of members across channels.
            created-at:
              type: string
              format: date-time
              readOnly: true
            updated-at:
              type: string
              format: date-time
              readOnly: true
        relationships:
          type: object
          properties:
            owner:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
                    type:
                      type: string
                      enum:
                      - users
                      title: Resource Type Name
                      description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
                  required:
                  - id
                  - type
              required:
              - data
              description: The identifier of the related object.
              title: Owner
              readOnly: true
            listing:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
                    type:
                      type: string
                      enum:
                      - listings
                      title: Resource Type Name
                      description: The [type](https://jsonapi.org/format/#document-resource-object-identification) member is used to describe resource objects that share common attributes and relationships.
                  required:
                  - id
                  - type
              required:
              - data
              description: The identifier of the related object.
              title: Listing
              readOnly: true
    CompsetMember:
      type: object
      description: One curated member of the comp set.
      properties:
        channel:
          type: string
          description: 'Source channel: `airbnb`, `vrbo`, or `bookingcom`.'
        channel-listing-id:
          type:
          - string
          - 'null'
          description: Channel-native listing id of the comparable property (the id in `url`); not a Beyond listing id.
        title:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        image:
          type:
          - string
          - 'null'
        bedrooms:
          type:
          - number
          - 'null'
          format: double
        bathrooms:
          type:
          - number
          - 'null'
          format: double
          description: Bathroom count (decimals denote half-baths, e.g. 1.5).
        room-type:
          type:
          - string
          - 'null'
        latitude:
          type:
          - number
          - 'null'
          format: double
        longitude:
          type:
          - number
          - 'null'
          format: double
        distance-km:
          type:
          - number
          - 'null'
          format: double
          description: Distance from the base listing in kilometers.
        rating:
          type:
          - number
          - 'null'
          format: double
        reviews-count:
          type:
          - integer
          - 'null'
        health-score:
          type:
          - number
          - 'null'
          format: double
        metrics:
          $ref: '#/components/schemas/CompsetMemberMetrics'
      required:
      - channel
      - channel-listing-id
      - metrics
    CompsetSource:
      type: object
      description: The base listing the comp set was built around.
      properties:
        bedrooms:
          type:
          - integer
          - 'null'
        bathrooms:
          type:
          - number
          - 'null'
          format: double
        latitude:
          type:
          - number
          - 'null'
          format: double
        longitude:
          type:
          - number
          - 'null'
          format: double
        address:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        market:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
          description: ISO currency code for the base listing.
        base-price:
          type:
          - number
          - 'null'
          format: double
          description: Average base price over the next 365 days.
        health-score:
          type:
          - integer
          - 'null'
        min-stay:
          type:
          - integer
          - 'null'
        metrics:
          $ref: '#/components/schemas/CompsetSourceMetrics'
      required:
      - metrics
  securitySchemes:
    oauth2:
      type: oauth2
      description: Use OAuth2 client credentials to mint an application token, or add `user_id` and optional `credential_id` in the Authorize dialog to request a user- or credential-scoped token.
      flows:
        clientCredentials:
          tokenUrl: /o/token/
          refreshUrl: /o/token/
          scopes:
            listings:read: Read listings
            listings:write: Modify listings
            reservations:read: Read reservations
            accounts:read: Read account information
            user:read: Read user information
            user:write: Create and modify users
            insights:read: Read market insights
            compsets:read: Read competitive set data
            neyoba:ask: Ask Neyoba
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: PersonalAccessToken
      description: Paste a `bpat_...` personal access token. PATs use the same Bearer header as OAuth2 tokens and must still include the runtime-required scopes for each endpoint, even though OpenAPI cannot encode scopes for non-OAuth bearer schemes.