openapi: 3.1.0
info:
  title: Taylor Morrison Home Search Communities Lots API
  description: Taylor Morrison Home Corporation's API for searching new home communities, available homes, floor plans, and lot inventory. Powers the digital homebuying experience including the industry-first fully online to-be-built reservation system.
  version: '1.0'
  contact:
    name: Taylor Morrison
    url: https://www.taylormorrison.com/
servers:
- url: https://www.taylormorrison.com/api
  description: Production
security:
- apiKeyAuth: []
tags:
- name: Lots
  description: Lot availability and details
paths:
  /lots:
    get:
      operationId: listLots
      summary: List Available Lots
      description: Returns available lots in a community for to-be-built home construction.
      tags:
      - Lots
      parameters:
      - name: community_id
        in: query
        required: true
        description: Community to list lots for
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Lot availability status
        schema:
          type: string
          enum:
          - available
          - reserved
          - sold
          - hold
      responses:
        '200':
          description: List of lots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LotList'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Lot:
      type: object
      properties:
        lot_id:
          type: string
        lot_number:
          type: string
          description: Lot number in the community plat
        status:
          type: string
          enum:
          - available
          - reserved
          - sold
          - hold
        price_premium:
          type: integer
          description: Lot premium above base price
        sqft:
          type: integer
          description: Lot size in square feet
        dimensions:
          type: string
          description: Lot dimensions (e.g., "60x120")
        backing:
          type: string
          description: What the lot backs to (greenbelt, pond, etc.)
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error description
    LotList:
      type: object
      properties:
        lots:
          type: array
          items:
            $ref: '#/components/schemas/Lot'
        total:
          type: integer
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
externalDocs:
  description: Taylor Morrison Website
  url: https://www.taylormorrison.com/