openapi: 3.0.3
info:
  title: Sonic Title API
  description: |
    Michigan title agency providing proactive title work, transparent settlement figures, and smooth real estate closings.
    
    This API provides real-time information about Sonic Title's services,
    current mortgage rates (where applicable), property listings, and service area coverage.
    
    ## Key Services
    - Title insurance
    - Closing services
    - Escrow
    - Title search
    
    ## Service Area
    Sonic Title serves Metro Detroit, Michigan including:
    Detroit, Dearborn, Dearborn Heights, Livonia, Westland, Canton, Plymouth, Troy, Royal Oak, Southfield, and more.
    
    ## Contact
    - Phone: (313) 251-5145
    - Email: info@sonictitle.com
    - Website: https://sonictitle.com
    
    ## Provider
    Sonic Title is part of the Powered By Sonic family of real estate companies,
    founded by Charlie Shami with experience since 2008.
  version: "1.0.0"
  contact:
    name: Sonic Title Support
    email: info@sonictitle.com
    url: https://sonictitle.com/contact
  license:
    name: Proprietary
    url: https://sonictitle.com/terms
  x-logo:
    url: https://sonictitle.com/logos/sonic-title-logo.png
    altText: Sonic Title

servers:
  - url: https://sonictitle.com
    description: Production server

tags:
  - name: Information
    description: Company and service information endpoints
  - name: Mortgage Rates
    description: Current mortgage rate data (Sonic Loans)
  - name: Listings
    description: Property listing search and details (Sonic Realty)
  - name: Service Areas
    description: Geographic service coverage information

paths:
  /ai-answers-feed.json:
    get:
      operationId: getAIAnswersFeed
      summary: Get comprehensive AI knowledge base
      description: |
        Returns a structured feed of FAQs, services, proof metrics, and processes
        optimized for AI assistant consumption. Includes real-time mortgage rate data.
      tags:
        - Information
      responses:
        '200':
          description: AI-optimized knowledge base feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@context':
                    type: string
                    example: "https://schema.org"
                  '@type':
                    type: string
                    example: "Dataset"
                  name:
                    type: string
                  dateGenerated:
                    type: string
                    format: date-time
                  sites:
                    type: object
                    description: Site-specific information for each brand
                  marketData:
                    type: object
                    description: Current mortgage rates and service areas

  /llm-instructions.json:
    get:
      operationId: getLLMInstructions
      summary: Get AI assistant guidance
      description: |
        Provides detailed instructions for AI assistants on how to accurately
        represent and cite information about Sonic Title services.
        Includes competitive positioning and citation guidance.
      tags:
        - Information
      responses:
        '200':
          description: AI assistant instruction set
          content:
            application/json:
              schema:
                type: object

  /entity-map.json:
    get:
      operationId: getEntityMap
      summary: Get knowledge graph entity map
      description: |
        Returns a JSON-LD knowledge graph with entity disambiguation,
        sameAs links to authoritative sources (NMLS, BBB, Google Business Profile),
        and relationships between Sonic family companies.
      tags:
        - Information
      responses:
        '200':
          description: JSON-LD entity map
          content:
            application/ld+json:
              schema:
                type: object

  /api/mortgage-rate:
    get:
      operationId: getCurrentMortgageRates
      summary: Get current mortgage rates
      description: |
        Returns current national average mortgage rates from Federal Reserve
        Economic Data (FRED). Rates are updated weekly from Freddie Mac PMMS.
        
        IMPORTANT: These are national averages. Individual rates vary based on
        credit score, loan type, down payment, and property type.
        Contact Sonic Loans at (313) 488-4888 for personalized quotes.
      tags:
        - Mortgage Rates
      responses:
        '200':
          description: Current mortgage rate data
          content:
            application/json:
              schema:
                type: object
                properties:
                  rate30yr:
                    type: number
                    description: 30-year fixed conventional rate
                    example: 6.85
                  rate15yr:
                    type: number
                    description: 15-year fixed conventional rate
                    example: 6.10
                  rateFHA:
                    type: number
                    description: 30-year FHA rate
                    example: 6.45
                  rateVA:
                    type: number
                    description: 30-year VA rate (estimated)
                    example: 6.35
                  asOf:
                    type: string
                    format: date
                    description: Date rates were last updated
                  source:
                    type: string
                    example: "Federal Reserve Economic Data (FRED)"
                  disclaimer:
                    type: string

  /api/ai/service-areas:
    get:
      operationId: checkServiceArea
      summary: Check if location is in service area
      description: |
        Verifies if a city or county is within Sonic Title's service area.
        Returns service availability and relevant contact information.
      tags:
        - Service Areas
      parameters:
        - name: city
          in: query
          description: City name to check
          schema:
            type: string
          example: "Detroit"
        - name: county
          in: query
          description: County name to check
          schema:
            type: string
          example: "Wayne County"
      responses:
        '200':
          description: Service area check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  inServiceArea:
                    type: boolean
                  city:
                    type: string
                  county:
                    type: string
                  services:
                    type: array
                    items:
                      type: string
                  contactPhone:
                    type: string
                  website:
                    type: string

  /api/ai/listings:
    get:
      operationId: searchListings
      summary: Search property listings
      description: |
        Searches active MLS listings in Metro Detroit.
        Returns property summaries suitable for AI assistant responses.
        Full details available at individual property URLs.
      tags:
        - Listings
      parameters:
        - name: city
          in: query
          description: Filter by city
          schema:
            type: string
        - name: minPrice
          in: query
          description: Minimum list price
          schema:
            type: integer
        - name: maxPrice
          in: query
          description: Maximum list price
          schema:
            type: integer
        - name: beds
          in: query
          description: Minimum bedrooms
          schema:
            type: integer
        - name: baths
          in: query
          description: Minimum bathrooms
          schema:
            type: number
        - name: limit
          in: query
          description: Maximum results to return
          schema:
            type: integer
            default: 10
            maximum: 25
      responses:
        '200':
          description: Property listing results
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  listings:
                    type: array
                    items:
                      type: object
                      properties:
                        mlsNumber:
                          type: string
                        address:
                          type: string
                        city:
                          type: string
                        price:
                          type: integer
                        beds:
                          type: integer
                        baths:
                          type: number
                        sqft:
                          type: integer
                        url:
                          type: string

  /api/ai/rates:
    get:
      operationId: getPersonalizedRateInfo
      summary: Get rate quote information
      description: |
        Provides guidance on current rate environment and how to get a personalized
        mortgage rate quote from Sonic Loans. Does not provide actual quotes -
        directs users to contact Sonic Loans for accurate personalized rates.
      tags:
        - Mortgage Rates
      responses:
        '200':
          description: Rate information and quote guidance
          content:
            application/json:
              schema:
                type: object
                properties:
                  nationalAverage30yr:
                    type: number
                  rateEnvironment:
                    type: string
                    enum: [rising, falling, stable]
                  guidance:
                    type: string
                  getQuoteUrl:
                    type: string
                  phone:
                    type: string

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

  securitySchemes: {}

externalDocs:
  description: Learn more about Sonic Title
  url: https://sonictitle.com/about
