BuyRecord Stays API

openapi: 3.2.0
info:
  title: BuyRecord Stays API
  description: 'BuyRecord publishes verified purchase outcomes (kept, kept and liked, complained, returned, with reasons) for products. Every outcome is tied to a proof of purchase: a connected Shopify store''s order record, or the merchant''s DKIM-signed order confirmation email. Scores run from 0 to 100, are shown from 5 verified outcomes and carry the number of outcomes and a confidence level. Scope: US online stores, 15 product categories, all prices; for products without a score, the price, availability, the store''s return policy and the rating the store publishes on its own site are returned, labelled apart from verified outcomes, with US CPSC recall flags. Verified stays (hotels and rentals) are scored the same way from DKIM-signed booking confirmations. Reading needs no key; submitting an outcome needs an API key or OAuth. No buyer personal data is stored. The same operations are available as an MCP server at https://api.buyrecord.app/mcp. Summary: https://buyrecord.app/llms.txt; methodology: https://buyrecord.app/methodology.html.'
  version: 0.1.0
tags:
- name: Stays
paths:
  /v1/stays/search:
    get:
      summary: Search Stays
      description: Hotels and rentals matching a name, each with its verified-stay summary.
      operationId: search_stays
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          description: Part of the property name.
          title: Query
        description: Part of the property name.
      - name: city
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 2
            maxLength: 100
          - type: 'null'
          title: City
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaySearchResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Stays
  /v1/stays/{property_id}:
    get:
      summary: Get Stay Outcomes
      description: Score, sample size, outcome breakdown and top reasons for one property, from verified stays only.
      operationId: get_stay_outcomes
      parameters:
      - name: property_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Property Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StayOutcomes'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Stays
  /v1/stays/outcomes:
    post:
      summary: Submit Stay Outcome
      description: 'Record how a hotel or rental stay went. Requires an API key.


        Proof: the platform''s original DKIM-signed booking confirmation email (Booking.com, Airbnb, Accor), with

        the reservation number, property name, city and dates as they appear in it. Accepted only after check-out

        and within 12 months of it. The email is processed in memory once and never stored.'
      operationId: submit_stay_outcome
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StaySubmission'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      tags:
      - Stays
components:
  schemas:
    StaySubmission:
      properties:
        property_name:
          type: string
          maxLength: 200
          minLength: 3
          title: Property Name
          description: Property name exactly as in the email.
        city:
          type: string
          maxLength: 100
          minLength: 2
          title: City
          description: City exactly as in the email.
        check_in:
          type: string
          format: date
          title: Check In
        check_out:
          type: string
          format: date
          title: Check Out
        outcome:
          type: string
          enum:
          - stayed_as_described
          - stayed_with_issues
          - cancelled_by_property
          - left_early
          title: Outcome
        reasons:
          items:
            type: string
            enum:
            - not_as_described
            - cleanliness
            - noise
            - check_in_problem
            - safety
            - overbooked
            - other
          type: array
          maxItems: 7
          title: Reasons
        proof:
          $ref: '#/components/schemas/StayConfirmationProof'
      type: object
      required:
      - property_name
      - city
      - check_in
      - check_out
      - outcome
      - proof
      title: StaySubmission
    StayOutcomeSummary:
      properties:
        score:
          anyOf:
          - type: number
          - type: 'null'
          title: Score
          description: 0 to 100. Null when sample_size is below min_sample.
        sample_size:
          type: integer
          title: Sample Size
          description: Verified stays counted.
        min_sample:
          type: integer
          title: Min Sample
        confidence:
          anyOf:
          - type: string
            enum:
            - low
            - medium
            - high
          - type: 'null'
          title: Confidence
          description: low under 10 verified stays, medium under 30, high from 30. Null when no score is shown.
        top_reasons:
          items:
            type: string
            enum:
            - not_as_described
            - cleanliness
            - noise
            - check_in_problem
            - safety
            - overbooked
            - other
          type: array
          title: Top Reasons
      type: object
      required:
      - score
      - sample_size
      - min_sample
      - confidence
      - top_reasons
      title: StayOutcomeSummary
    StaySearchResult:
      properties:
        properties:
          items:
            $ref: '#/components/schemas/StayProperty'
          type: array
          title: Properties
      type: object
      required:
      - properties
      title: StaySearchResult
    SubmissionResult:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          type: string
          enum:
          - accepted
          - quarantined
          title: Status
        status_reason:
          type: string
          enum:
          - verified
          - proof_not_verifiable
          - pending_merchant_verification
          title: Status Reason
      type: object
      required:
      - id
      - status
      - status_reason
      title: SubmissionResult
    StayProperty:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
          description: Property name as written in the platform's confirmation, cleaned and capped at 200 characters.
        city:
          type: string
          title: City
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2, lowercase, when known.
        platforms:
          items:
            type: string
            enum:
            - booking
            - airbnb
            - accor
          type: array
          title: Platforms
          description: Platforms through which verified stays were booked.
        outcomes:
          $ref: '#/components/schemas/StayOutcomeSummary'
          description: Verified stays only.
      type: object
      required:
      - id
      - name
      - city
      - country
      - platforms
      - outcomes
      title: StayProperty
    StayConfirmationProof:
      properties:
        type:
          type: string
          const: stay_confirmation
          title: Type
        raw_email_base64:
          type: string
          maxLength: 2800000
          title: Raw Email Base64
          description: The platform's original booking confirmation email (.eml, RFC 5322), base64-encoded. Its DKIM signature is verified; the email is processed in memory once and never stored.
        reservation_number:
          type: string
          maxLength: 60
          minLength: 4
          title: Reservation Number
          description: Reservation or confirmation number as it appears in the email. Hashed on arrival, never stored.
      type: object
      required:
      - type
      - raw_email_base64
      - reservation_number
      title: StayConfirmationProof
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    StayOutcomes:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
          description: Property name as written in the platform's confirmation, cleaned and capped at 200 characters.
        city:
          type: string
          title: City
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2, lowercase, when known.
        platforms:
          items:
            type: string
            enum:
            - booking
            - airbnb
            - accor
          type: array
          title: Platforms
          description: Platforms through which verified stays were booked.
        outcomes:
          $ref: '#/components/schemas/StayOutcomeSummary'
          description: Verified stays only.
        breakdown:
          additionalProperties:
            type: integer
          propertyNames:
            enum:
            - stayed_as_described
            - stayed_with_issues
            - cancelled_by_property
            - left_early
          type: object
          title: Breakdown
        computed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Computed At
      type: object
      required:
      - id
      - name
      - city
      - country
      - platforms
      - outcomes
      - breakdown
      - computed_at
      title: StayOutcomes
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (br_live_...). Required for writing.
      scheme: bearer