Rentberry Listings API

openapi: 3.2.0
info:
  title: Rentberry Listings API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Listings
  description: Listings
paths:
  /v{version}/apartment/description/stream:
    post:
      tags:
      - Listings
      summary: Generate listing description as stream
      description: Available since API version 4. Generates a listing description using AI and returns it as a Server-Sent Events (SSE) stream.
      operationId: post_api_v4_apartment_description_stream
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                title:
                  description: Title of the listing
                  type: string
                description:
                  description: Current description of the listing
                  type: string
                price:
                  description: Price of the listing
                  type: number
                  format: float
                bedroomsCount:
                  description: Number of bedrooms
                  type: integer
                bathroomsCount:
                  description: Number of bathrooms
                  type: integer
                apartmentPictures:
                  description: Array of picture IDs for context
                  type: array
                  items:
                    properties:
                      id:
                        description: Picture ID
                        type: integer
                    type: object
              type: object
      responses:
        '200':
          description: Server-Sent Events stream with generated description
          headers:
            Content-Type:
              description: Event stream content type
              schema:
                type: string
                example: text/event-stream
            Cache-Control:
              description: Cache control header
              schema:
                type: string
                example: no-cache
            X-Accel-Buffering:
              description: Nginx buffering control
              schema:
                type: string
                example: 'no'
          content:
            text/event-stream: []
        '400':
          description: Bad request - Validation failed
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
  /v{version}/apartment/favorite:
    get:
      tags:
      - Listings
      summary: Get favorite listings
      description: Available since API version 2. Returns a paginated list of the authenticated user's favorite listings.
      operationId: get_api_v2_apartment_favorite_get
      parameters:
      - name: beforeId
        in: query
        description: Get listings before this ID (for cursor-based pagination)
        schema:
          type: integer
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of favorite listings
          content:
            application/json:
              schema:
                properties:
                  items:
                    description: List of favorite listings
                    type: array
                    items:
                      $ref: '#/components/schemas/FavoriteApartmentsUsers'
                  pagination:
                    description: Pagination information
                    type: object
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
    post:
      tags:
      - Listings
      summary: Add listing to favorites
      description: Available since API version 1. Adds a listing to the authenticated user's favorites list.
      operationId: post_api_v1_apartment_favorite_add
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - apartment
              properties:
                apartment:
                  description: ID of the listing to add to favorites
                  type: integer
                  example: 12345
              type: object
      responses:
        '200':
          description: Listing added to favorites successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
  /v{version}/apartment/favorite/bulk:
    post:
      tags:
      - Listings
      summary: Add multiple listings to favorites
      description: Available since API version 4. Adds multiple listings to the authenticated user's favorites list in bulk.
      operationId: post_api_v4_listing_favorite_add_bulk
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - listingsIds
              properties:
                listingsIds:
                  description: Array of listing IDs to add to favorites
                  type: array
                  items:
                    description: Listing ID
                    type: integer
                  example:
                  - 12345
                  - 67890
                  - 11111
              type: object
      responses:
        '200':
          description: Listings added to favorites successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '400':
          description: Bad request - Invalid input data
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
  /v{version}/apartment/favorite/{id}:
    delete:
      tags:
      - Listings
      summary: Remove listing from favorites
      description: Available since API version 1. Removes a listing from the authenticated user's favorites list.
      operationId: delete_api_v1_apartment_favorite_delete
      parameters:
      - name: id
        in: path
        description: Listing ID to remove from favorites
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Listing removed from favorites successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
  /v{version}/listing/{listing}/inquiry:
    post:
      tags:
      - Listings
      summary: Create inquiry for a listing
      description: Available since API version 1. Creates an inquiry for a specific listing. Rate limited to prevent spam.
      operationId: post_api_v1_listing_inquiry_create
      parameters:
      - name: listing
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InquiryType'
      responses:
        '200':
          description: Inquiry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Inquiry'
        '400':
          description: Bad request - Validation failed
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Listing not found
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                type: string
              example: Too many requests from one IP
  /v{version}/listing/{listing}/inquiry/info:
    get:
      tags:
      - Listings
      summary: Get inquiry information for a listing
      description: Available since API version 4. Returns statistics and information about inquiries for a specific listing.
      operationId: get_api_v4_listing_inquiry_info
      parameters:
      - name: listing
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Inquiry information for the listing
          content:
            application/json:
              schema:
                properties:
                  applyCount:
                    description: Total number of inquiries
                    type: integer
                  countrySettings:
                    description: Country-specific settings
                    type: object
                  stats:
                    description: Competitive statistics (prices floored to integers)
                    type: object
                    additionalProperties:
                      type: integer
                type: object
              example:
                applyCount: 15
                stats:
                  avgPrice: 2500
                  maxPrice: 3000
                  minPrice: 2000
                countrySettings:
                  currency: USD
        '404':
          description: Listing not found
  /v{version}/apartment:
    get:
      tags:
      - Listings
      summary: Get homeowner listings list
      description: Available since API version 1. Returns a paginated list of listings owned by the authenticated user with notification counters.
      operationId: get_api_v1_apartment_list
      parameters:
      - name: active
        in: query
        description: Filter by active status (true = active listings, false = all listings)
        schema:
          type: boolean
          default: true
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        description: Number of items per page (varies based on active status and page)
        schema:
          type: integer
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of homeowner listings with counters
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListingWithCountersResponse'
                  pagination:
                    type: object
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have required permissions
      security:
      - XAuthToken: []
    post:
      tags:
      - Listings
      summary: Create new listing
      description: Available since API version 1. Creates a new listing for the authenticated user. Requires advanced features subscription for certain users.
      operationId: post_api_v1_apartment_new
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ListingType'
      responses:
        '200':
          description: Listing created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing4'
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '402':
          description: Payment required - Advanced features subscription needed
        '405':
          description: (Real code 1020) Cannot set pet deposit without selecting cat or dog
      security:
      - XAuthToken: []
  /v{version}/apartment/ids:
    get:
      tags:
      - Listings
      summary: Get homeowner listings IDs
      description: Available since API version 4. Returns a simple list of listing IDs owned by the authenticated user.
      operationId: get_api_v4_listings_ids_list
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of listing IDs
          content:
            application/json:
              schema:
                properties:
                  ids:
                    type: array
                    items:
                      type: integer
                    example:
                    - 12345
                    - 67890
                    - 11111
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
  /v{version}/apartment/{id}:
    get:
      tags:
      - Listings
      summary: Get listing details (v3)
      description: Available since API version 3. Returns detailed information about a specific listing.
      operationId: getListingV3
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Listing details
          content:
            application/json:
              schema:
                description: Detailed listing information
                type: object
        '404':
          description: Listing not found or not visible
    put:
      tags:
      - Listings
      summary: Restore archived listing
      description: Available since API version 1. Restores an archived listing to active status.
      operationId: put_api_v1_apartment_un_archive
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Listing restored successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '405':
          description: (Real code 1007) Not your listing - Cannot restore listing owned by another user
        '406':
          description: (Real code 1011) Cannot restore deleted listing
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
    post:
      tags:
      - Listings
      summary: Update existing listing
      description: Available since API version 1. Updates an existing listing owned by the authenticated user. Cannot update rented listings.
      operationId: post_api_v1_apartment_edit
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ListingType'
      responses:
        '200':
          description: Listing updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '405':
          description: (Real code 1013) Not your listing - Cannot edit listing owned by another user
        '406':
          description: (Real code 1025) Cannot edit rented listing
        '407':
          description: (Real code 1020) Cannot set pet deposit without selecting cat or dog
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
    delete:
      tags:
      - Listings
      summary: Archive or delete listing
      description: Available since API version 1. Archives or permanently deletes a listing owned by the authenticated user. Cannot delete rented listings.
      operationId: delete_api_v1_apartment_archive
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: delete
        in: query
        description: Permanently delete listing (true) or just archive it (false)
        schema:
          type: boolean
          default: false
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Listing archived or deleted successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '405':
          description: (Real code 1004) Not your listing - Cannot archive/delete listing owned by another user
        '406':
          description: (Real code 1021) Cannot archive/delete rented listing
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
  /v{version}/apartment/{id}/view:
    get:
      tags:
      - Listings
      summary: View listing details (public)
      description: Available since API version 4. Returns listing details for public viewing, including expired MLS listings with redirect URLs.
      operationId: get_api_v4_apartment_view
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Listing details for public viewing
          content:
            application/json:
              schema:
                description: Listing information with localized data
                type: object
        '410':
          description: Listing expired or not viewable
          content:
            application/json:
              schema:
                properties:
                  redirect:
                    description: Redirect URL for expired MLS listings
                    type: string
                type: object
        '404':
          description: Listing not found
  /v{version}/apartment/{id}/competitors:
    get:
      tags:
      - Listings
      summary: Get listing competitors
      description: Available since API version 1. Returns paginated list of competing applications for a specific listing.
      operationId: get_api_v1_apartment_get_competitors
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of competing applications
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      description: Competing application data
                      type: object
                  pagination:
                    type: object
                type: object
        '404':
          description: Listing not found or not active
  /v{version}/apartment/application/info/{id}:
    get:
      tags:
      - Listings
      summary: Get application info for listing
      description: Available since API version 1. Returns statistical information about applications for a specific listing, including competitor data and country settings.
      operationId: get_api_v1_apartment_application_info_in_apartment
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          maximum: 2147483646
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Application statistics and competitor information
          content:
            application/json:
              schema:
                properties:
                  applyCount:
                    description: Total number of applications
                    type: integer
                  stats:
                    description: Statistical data (prices floored to integers)
                    type: object
                    additionalProperties:
                      type: integer
                  highest:
                    description: Highest applications by price and deposit
                    properties:
                      byPrice:
                        type: array
                        items:
                          type: object
                      byDeposit:
                        type: array
                        items:
                          type: object
                    type: object
                  countrySettings:
                    description: Country-specific settings
                    type: object
                type: object
        '404':
          description: Listing not found
  /v{version}/apartment/virtual-tours:
    get:
      tags:
      - Listings
      summary: Get listings with virtual tours
      description: Available since API version 1. Returns paginated list of listings that have virtual tours available. Results are cached for performance.
      operationId: get_api_v1_apartment_with_virtual_tours
      parameters:
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        description: Number of items per page
        schema:
          type: integer
          default: 3
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of listings with virtual tours
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing5'
                  pagination:
                    type: object
                type: object
  /v{version}/apartment/maintenance/{id}:
    post:
      tags:
      - Listings
      summary: Create maintenance request
      description: Available since API version 1. Creates a new maintenance request for a listing. Only tenants with approved applications can create maintenance requests.
      operationId: post_api_v1_maintenance_new
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - description
              - priority
              properties:
                description:
                  description: Detailed description of the maintenance issue
                  type: string
                  maxLength: 255
                  minLength: 2
                  example: The kitchen sink is leaking and needs immediate attention.
                priority:
                  description: Priority level of the maintenance request
                  type: string
                  enum:
                  - '1'
                  - '2'
                  - '3'
                  example: high
                apartmentApplyId:
                  description: ID of the approved application that grants permission to create maintenance requests
                  type: integer
                  example: 12345
              type: object
      responses:
        '200':
          description: Maintenance request created successfully and notification email sent to homeowner
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to create maintenance requests for this listing
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
  /v{version}/apartment/open-house/applies/{id}:
    get:
      tags:
      - Listings
      summary: Get open house applications for listing
      description: Available since API version 1. Returns paginated list of open house applications for a specific listing owned by the authenticated user.
      operationId: get_api_v1_apartment_tour_applies_by_tennants
      parameters:
      - name: id
        in: path
        description: Listing ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: active
        in: query
        description: Filter by active status (true = active applications, false = all applications)
        schema:
          type: boolean
          default: true
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of open house applications
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      description: Open house application response
                      type: object
                  pagination:
                    type: object
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not own this listing
        '404':
          description: Listing not found
      security:
      - XAuthToken: []
  /v{version}/apartment/open-house/apply:
    post:
      tags:
      - Listings
      summary: Create open house application
      description: Available since API version 1. Creates an application for an open house viewing. Rate limited to prevent spam.
      operationId: post_api_v1_apartment_tour_apply
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - listing
              - name
              - email
              - phone
              properties:
                listing:
                  description: Listing ID for the open house
                  type: integer
                  example: 12345
                name:
                  description: Applicant's full name
                  type: string
                  maxLength: 255
                  example: John Doe
                email:
                  description: Applicant's email address
                  type: string
                  format: email
                  example: john.doe@example.com
                phone:
                  description: Applicant's phone number
                  type: integer
                  maximum: 999999999999999
                  minimum: 1000000
                  example: 1234567890
                message:
                  description: Additional message from applicant
                  type: string
                  example: I am interested in viewing this property.
              type: object
      responses:
        '200':
          description: Open house application created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenHouseApplication'
        '400':
          description: Bad request - Validation failed
        '405':
          description: (Real code 21001) Feature disabled - Open house feature is not available
        '429':
          description: Too many requests - Rate limit exceeded
  /v{version}/apartment/open-house/apply-mls:
    post:
      tags:
      - Listings
      summary: Create open house application for MLS listing
      description: Available since API version 4. Creates an application for an open house viewing for MLS listings. Does not check for existing users. Rate limited to prevent spam.
      operationId: post_api_v4_mls_listing_open_house_apply
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - listing
              - name
              - email
              - phone
              properties:
                listing:
                  description: MLS listing ID for the open house
                  type: integer
                  example: 12345
                name:
                  description: Applicant's full name
                  type: string
                  maxLength: 255
                  example: John Doe
                email:
                  description: Applicant's email address
                  type: string
                  format: email
                  example: john.doe@example.com
                phone:
                  description: Applicant's phone number
                  type: integer
                  maximum: 999999999999999
                  minimum: 1000000
                  example: 1234567890
    

# --- truncated at 32 KB (195 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/openapi/rentberry-listings-api-openapi.yml