{
  "openapi": "3.1.0",
  "info": {
    "title": "BNBCalc Airbnb Data API",
    "version": "1",
    "description": "Use the BNBCalc Airbnb Data API to get property revenue, occupancy, ADR, active Airbnb comparable listings, percentiles, investment metrics, and hosted report URLs for apps, reports, underwriting, and management tools.\n\nAll API endpoints use HTTPS and return JSON responses. Keep API keys on your server, not in browser or mobile client code. External API routes are currently throttled at 100 requests per second and use standard HTTP response codes to indicate success or failure.",
    "termsOfService": "https://www.bnbcalc.com/terms-of-service",
    "license": {
      "name": "Proprietary",
      "url": "https://www.bnbcalc.com/terms-of-service"
    },
    "contact": {
      "name": "BNBCalc",
      "url": "https://www.bnbcalc.com/support"
    }
  },
  "externalDocs": {
    "description": "Airbnb Data API Documentation",
    "url": "https://www.bnbcalc.com/developers/rest-api/docs"
  },
  "servers": [
    {
      "url": "https://atlas.bnbcalc.com"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Create analyses",
      "description": "Pick the endpoint that matches the deal you're modeling. All four take the same location input (lat/lng or a full address) and return JSON plus a hosted public BNBCalc report URL."
    },
    {
      "name": "AI enrichment",
      "description": "AI enrichment is opt-in per request through addAIComps and addAIExpenseEstimates, and every AI step is time-bounded and fails open. A request that asked for AI still returns 201 with a complete, fully recalculated analysis; anything that could not run is reported in the top-level warnings array instead of raising an error."
    }
  ],
  "paths": {
    "/v1/external/analysis/create/buy": {
      "post": {
        "operationId": "createBuyAnalysis",
        "summary": "Create Buy Analysis",
        "description": "Create a buy analysis for a short-term rental acquisition. Send location, property details, and purchase price to return projected revenue, occupancy, comps, cash flow, and ROI metrics.\n\nAI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.\n\nAI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.\n\nWhen an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.\n\nEach AI step that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI steps that completed, with no base call fee.",
        "tags": [
          "Create analyses"
        ],
        "x-mcp-tool": "create_buy_analysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "description": "Latitude coordinate (must be provided with lng if fullAddress is not used)",
                    "examples": [
                      27.7676
                    ]
                  },
                  "lng": {
                    "type": "number",
                    "description": "Longitude coordinate (must be provided with lat if fullAddress is not used)",
                    "examples": [
                      -82.6403
                    ]
                  },
                  "fullAddress": {
                    "type": "string",
                    "description": "Complete property address (can be used instead of lat/lng coordinates)",
                    "examples": [
                      "4935 2nd Avenue North, St. Petersburg, FL 33703"
                    ]
                  },
                  "purchasePriceUSD": {
                    "type": "number",
                    "description": "Purchase price in USD",
                    "examples": [
                      350000
                    ]
                  },
                  "bedrooms": {
                    "type": "number",
                    "description": "Number of bedrooms",
                    "examples": [
                      3
                    ]
                  },
                  "bathrooms": {
                    "type": "number",
                    "description": "Number of bathrooms",
                    "examples": [
                      2
                    ]
                  },
                  "accomodates": {
                    "type": "number",
                    "description": "Number of guests the property can accommodate",
                    "examples": [
                      6
                    ]
                  },
                  "monthlyRentUSD": {
                    "type": "number",
                    "description": "Expected monthly rent in USD for long-term rental",
                    "examples": [
                      2500
                    ]
                  },
                  "interestRatePercentage": {
                    "type": "number",
                    "description": "Interest rate percentage (0-15)",
                    "examples": [
                      5.1
                    ]
                  },
                  "downPaymentPercentage": {
                    "type": "number",
                    "description": "Down payment percentage (0-40)",
                    "examples": [
                      25
                    ]
                  },
                  "mortgageLength": {
                    "type": "number",
                    "description": "Mortgage length in years (0-30)",
                    "examples": [
                      15
                    ]
                  },
                  "squareFeet": {
                    "type": "number",
                    "description": "Property square footage",
                    "examples": [
                      1500
                    ]
                  },
                  "state": {
                    "type": "string",
                    "description": "State name",
                    "examples": [
                      "Florida"
                    ]
                  },
                  "city": {
                    "type": "string",
                    "description": "City name",
                    "examples": [
                      "St. Petersburg"
                    ]
                  },
                  "county": {
                    "type": "string",
                    "description": "County name",
                    "examples": [
                      "Pinellas County"
                    ]
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal/ZIP code",
                    "examples": [
                      "33703"
                    ]
                  },
                  "country": {
                    "type": "string",
                    "description": "Country name",
                    "examples": [
                      "United States"
                    ]
                  },
                  "street": {
                    "type": "string",
                    "description": "Street name",
                    "examples": [
                      "2nd Avenue North"
                    ]
                  },
                  "streetNumber": {
                    "type": "string",
                    "description": "Street number",
                    "examples": [
                      "4935"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "description": "Unit/apartment number if applicable"
                  },
                  "addAIComps": {
                    "type": "boolean",
                    "description": "Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.",
                    "examples": [
                      true
                    ]
                  },
                  "addAIExpenseEstimates": {
                    "type": "boolean",
                    "description": "Estimate operating expenses with AI instead of using category defaults",
                    "examples": [
                      true
                    ]
                  }
                },
                "required": [
                  "purchasePriceUSD",
                  "bedrooms",
                  "bathrooms",
                  "accomodates"
                ],
                "anyOf": [
                  {
                    "required": [
                      "lat",
                      "lng"
                    ]
                  },
                  {
                    "required": [
                      "fullAddress"
                    ]
                  }
                ]
              },
              "example": {
                "lat": 27.7676,
                "lng": -82.6403,
                "bedrooms": 3,
                "bathrooms": 2,
                "accomodates": 6,
                "purchasePriceUSD": 400000
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Projected ADR, occupancy, annual revenue, cash flow, cap rate, cash-on-cash return, percentiles, a hosted report URL, and the active Airbnb comparables behind the estimate.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "ratePerNightUSD": {
                          "type": "number"
                        },
                        "occupancyRatePercentage": {
                          "type": "number"
                        },
                        "bedrooms": {
                          "type": "number"
                        },
                        "bathrooms": {
                          "type": "number"
                        },
                        "commonSpaces": {
                          "type": "number"
                        },
                        "accomodates": {
                          "type": "number"
                        },
                        "fullAddress": {
                          "type": "string"
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "revenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "adr": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "occupancy": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "quartiles": {
                          "type": "object",
                          "properties": {
                            "25th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "50th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "75th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "90th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "comparables": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "airbnbId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "listingUrl": {
                                "type": "string"
                              },
                              "bedrooms": {
                                "type": "number"
                              },
                              "bathrooms": {
                                "type": "number"
                              },
                              "accommodates": {
                                "type": "number"
                              },
                              "annualRevenueUSD": {
                                "type": "number"
                              },
                              "occupancyRatePercentage": {
                                "type": "number"
                              },
                              "averageDailyRateUSD": {
                                "type": "number"
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "photo_urls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "downPaymentPercentage": {
                          "type": "number"
                        },
                        "mortgageLength": {
                          "type": "number"
                        },
                        "yearsRemainingOnMortgage": {
                          "type": "number"
                        },
                        "interestRatePercentage": {
                          "type": "number"
                        },
                        "propertyTaxPercentage": {
                          "type": "number"
                        },
                        "monthlyRevenueUSD": {
                          "type": "number"
                        },
                        "monthlyExpensesUSD": {
                          "type": "number"
                        },
                        "monthlyTaxesUSD": {
                          "type": "number"
                        },
                        "yearOneRevenueUSD": {
                          "type": "number"
                        },
                        "yearOneOperatingIncomeUSD": {
                          "type": "number"
                        },
                        "yearOneMorgageAndTaxesUSD": {
                          "type": "number"
                        },
                        "yearOneCashFlowUSD": {
                          "type": "number"
                        },
                        "yearOneCashOnCashPercentage": {
                          "type": "number"
                        },
                        "yearOneCapRatePercentage": {
                          "type": "number"
                        },
                        "yearOneReturnOnInvestmentPercentage": {
                          "type": "number"
                        },
                        "yearOnePrincipalPaydownUSD": {
                          "type": "number"
                        },
                        "yearOnePrincipalPaidUSD": {
                          "type": "number"
                        },
                        "yearOneAppreciationUSD": {
                          "type": "number"
                        },
                        "totalCashInvestment": {
                          "type": "number"
                        },
                        "ltrPerMonthUSD": {
                          "type": "number"
                        },
                        "ltrMonthlyExpensesPercentage": {
                          "type": "number"
                        },
                        "revenueBasis": {
                          "type": "string"
                        },
                        "actualAnnualRevenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "average": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "_id": "000000000000000000000000",
                    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
                    "currency": "USD",
                    "ratePerNightUSD": 364.73770491803276,
                    "occupancyRatePercentage": 48,
                    "bedrooms": 4,
                    "bathrooms": 4,
                    "commonSpaces": 1,
                    "accomodates": 12,
                    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
                    "location": {
                      "type": "Point",
                      "coordinates": [
                        -82.6403,
                        27.7676
                      ]
                    },
                    "revenue": {
                      "p25": 48210,
                      "p50": 58440,
                      "p75": 63944.76398163934,
                      "p90": 74280,
                      "avg": 60310
                    },
                    "adr": {
                      "p25": 214,
                      "p50": 288,
                      "p75": 364.73770491803276,
                      "p90": 431,
                      "avg": 318
                    },
                    "occupancy": {
                      "p25": 0.38,
                      "p50": 0.44,
                      "p75": 0.48,
                      "p90": 0.56,
                      "avg": 0.46
                    },
                    "quartiles": {
                      "25th_percentile": {
                        "average_daily_rate": 214,
                        "occupancy_rate": 38,
                        "revenue": 48210
                      },
                      "50th_percentile": {
                        "average_daily_rate": 288,
                        "occupancy_rate": 44,
                        "revenue": 58440
                      },
                      "75th_percentile": {
                        "average_daily_rate": 364.73770491803276,
                        "occupancy_rate": 48,
                        "revenue": 63944.76398163934
                      },
                      "90th_percentile": {
                        "average_daily_rate": 431,
                        "occupancy_rate": 56,
                        "revenue": 74280
                      }
                    },
                    "comparables": [
                      {
                        "airbnbId": "12345678",
                        "name": "Modern 4BR near downtown",
                        "listingUrl": "https://www.airbnb.com/rooms/12345678",
                        "bedrooms": 4,
                        "bathrooms": 3,
                        "accommodates": 10,
                        "annualRevenueUSD": 68420,
                        "occupancyRatePercentage": 52,
                        "averageDailyRateUSD": 361,
                        "distanceMiles": 0.4,
                        "photo_urls": [
                          "https://a0.muscache.com/im/pictures/example/cover.jpg",
                          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
                          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
                        ]
                      }
                    ],
                    "downPaymentPercentage": 20,
                    "mortgageLength": 30,
                    "yearsRemainingOnMortgage": 30,
                    "interestRatePercentage": 4,
                    "propertyTaxPercentage": 0.75,
                    "monthlyRevenueUSD": 5328.730331803278,
                    "monthlyExpensesUSD": 1474.1603364983607,
                    "monthlyTaxesUSD": 250,
                    "yearOneRevenueUSD": 63944.76398163934,
                    "yearOneOperatingIncomeUSD": 46254.83994365901,
                    "yearOneMorgageAndTaxesUSD": 21324,
                    "yearOneCashFlowUSD": 24930.83994365901,
                    "yearOneCashOnCashPercentage": 24.86817214984141,
                    "yearOneCapRatePercentage": 11.563709985914752,
                    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
                    "yearOnePrincipalPaydownUSD": 85635.31658640636,
                    "yearOnePrincipalPaidUSD": 5635.31658640636,
                    "yearOneAppreciationUSD": 12000,
                    "totalCashInvestment": 100252,
                    "ltrPerMonthUSD": 1500,
                    "ltrMonthlyExpensesPercentage": 10,
                    "revenueBasis": "full_time_potential",
                    "actualAnnualRevenue": {
                      "p25": 24180,
                      "p50": 36920,
                      "p75": 47350,
                      "p90": 58810,
                      "average": 37640
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "$ref": "#/components/responses/502"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        }
      }
    },
    "/v1/external/analysis/create/arb": {
      "post": {
        "operationId": "createArbitrageAnalysis",
        "summary": "Create Arbitrage Analysis",
        "description": "Create a rental arbitrage analysis for a leased property. Send monthly rent, location, and property details to return projected Airbnb revenue, cash flow, and comparable listings.\n\nAI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.\n\nAI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.\n\nWhen an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.\n\nEach AI step that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI steps that completed, with no base call fee.",
        "tags": [
          "Create analyses"
        ],
        "x-mcp-tool": "create_arbitrage_analysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "description": "Latitude coordinate (must be provided with lng if fullAddress is not used)",
                    "examples": [
                      27.7676
                    ]
                  },
                  "lng": {
                    "type": "number",
                    "description": "Longitude coordinate (must be provided with lat if fullAddress is not used)",
                    "examples": [
                      -82.6403
                    ]
                  },
                  "fullAddress": {
                    "type": "string",
                    "description": "Complete property address (can be used instead of lat/lng coordinates)",
                    "examples": [
                      "4935 2nd Avenue North, St. Petersburg, FL 33703"
                    ]
                  },
                  "monthlyRentUSD": {
                    "type": "number",
                    "description": "Expected monthly rent in USD for long-term rental",
                    "examples": [
                      2500
                    ]
                  },
                  "bedrooms": {
                    "type": "number",
                    "description": "Number of bedrooms",
                    "examples": [
                      3
                    ]
                  },
                  "bathrooms": {
                    "type": "number",
                    "description": "Number of bathrooms",
                    "examples": [
                      2
                    ]
                  },
                  "accomodates": {
                    "type": "number",
                    "description": "Number of guests the property can accommodate",
                    "examples": [
                      6
                    ]
                  },
                  "purchasePriceUSD": {
                    "type": "number",
                    "description": "Purchase price in USD",
                    "examples": [
                      350000
                    ]
                  },
                  "squareFeet": {
                    "type": "number",
                    "description": "Property square footage",
                    "examples": [
                      1500
                    ]
                  },
                  "state": {
                    "type": "string",
                    "description": "State name",
                    "examples": [
                      "Florida"
                    ]
                  },
                  "city": {
                    "type": "string",
                    "description": "City name",
                    "examples": [
                      "St. Petersburg"
                    ]
                  },
                  "county": {
                    "type": "string",
                    "description": "County name",
                    "examples": [
                      "Pinellas County"
                    ]
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal/ZIP code",
                    "examples": [
                      "33703"
                    ]
                  },
                  "country": {
                    "type": "string",
                    "description": "Country name",
                    "examples": [
                      "United States"
                    ]
                  },
                  "street": {
                    "type": "string",
                    "description": "Street name",
                    "examples": [
                      "2nd Avenue North"
                    ]
                  },
                  "streetNumber": {
                    "type": "string",
                    "description": "Street number",
                    "examples": [
                      "4935"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "description": "Unit/apartment number if applicable"
                  },
                  "addAIComps": {
                    "type": "boolean",
                    "description": "Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.",
                    "examples": [
                      true
                    ]
                  },
                  "addAIExpenseEstimates": {
                    "type": "boolean",
                    "description": "Estimate operating expenses with AI instead of using category defaults",
                    "examples": [
                      true
                    ]
                  }
                },
                "required": [
                  "monthlyRentUSD",
                  "bedrooms",
                  "bathrooms",
                  "accomodates"
                ],
                "anyOf": [
                  {
                    "required": [
                      "lat",
                      "lng"
                    ]
                  },
                  {
                    "required": [
                      "fullAddress"
                    ]
                  }
                ]
              },
              "example": {
                "lat": 27.7676,
                "lng": -82.6403,
                "bedrooms": 3,
                "bathrooms": 2,
                "accomodates": 6,
                "monthlyRentUSD": 2000
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Projected revenue and cash flow for a rental-arbitrage unit, net of your monthly rent, plus percentiles, a hosted report URL, and supporting comparables.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "ratePerNightUSD": {
                          "type": "number"
                        },
                        "occupancyRatePercentage": {
                          "type": "number"
                        },
                        "bedrooms": {
                          "type": "number"
                        },
                        "bathrooms": {
                          "type": "number"
                        },
                        "commonSpaces": {
                          "type": "number"
                        },
                        "accomodates": {
                          "type": "number"
                        },
                        "fullAddress": {
                          "type": "string"
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "revenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "adr": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "occupancy": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "quartiles": {
                          "type": "object",
                          "properties": {
                            "25th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "50th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "75th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "90th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "comparables": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "airbnbId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "listingUrl": {
                                "type": "string"
                              },
                              "bedrooms": {
                                "type": "number"
                              },
                              "bathrooms": {
                                "type": "number"
                              },
                              "accommodates": {
                                "type": "number"
                              },
                              "annualRevenueUSD": {
                                "type": "number"
                              },
                              "occupancyRatePercentage": {
                                "type": "number"
                              },
                              "averageDailyRateUSD": {
                                "type": "number"
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "photo_urls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "monthlyRentUSD": {
                          "type": "number"
                        },
                        "yearOneRentUSD": {
                          "type": "number"
                        },
                        "monthlyRevenueUSD": {
                          "type": "number"
                        },
                        "monthlyExpensesUSD": {
                          "type": "number"
                        },
                        "yearOneRevenueUSD": {
                          "type": "number"
                        },
                        "yearOneOperatingIncomeUSD": {
                          "type": "number"
                        },
                        "yearOneCashFlowUSD": {
                          "type": "number"
                        },
                        "yearOneCashOnCashPercentage": {
                          "type": "number"
                        },
                        "totalCashInvestment": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "_id": "000000000000000000000000",
                    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
                    "currency": "USD",
                    "ratePerNightUSD": 364.73770491803276,
                    "occupancyRatePercentage": 48,
                    "bedrooms": 4,
                    "bathrooms": 4,
                    "commonSpaces": 1,
                    "accomodates": 12,
                    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
                    "location": {
                      "type": "Point",
                      "coordinates": [
                        -82.6403,
                        27.7676
                      ]
                    },
                    "revenue": {
                      "p25": 48210,
                      "p50": 58440,
                      "p75": 63944.76398163934,
                      "p90": 74280,
                      "avg": 60310
                    },
                    "adr": {
                      "p25": 214,
                      "p50": 288,
                      "p75": 364.73770491803276,
                      "p90": 431,
                      "avg": 318
                    },
                    "occupancy": {
                      "p25": 0.38,
                      "p50": 0.44,
                      "p75": 0.48,
                      "p90": 0.56,
                      "avg": 0.46
                    },
                    "quartiles": {
                      "25th_percentile": {
                        "average_daily_rate": 214,
                        "occupancy_rate": 38,
                        "revenue": 48210
                      },
                      "50th_percentile": {
                        "average_daily_rate": 288,
                        "occupancy_rate": 44,
                        "revenue": 58440
                      },
                      "75th_percentile": {
                        "average_daily_rate": 364.73770491803276,
                        "occupancy_rate": 48,
                        "revenue": 63944.76398163934
                      },
                      "90th_percentile": {
                        "average_daily_rate": 431,
                        "occupancy_rate": 56,
                        "revenue": 74280
                      }
                    },
                    "comparables": [
                      {
                        "airbnbId": "12345678",
                        "name": "Modern 4BR near downtown",
                        "listingUrl": "https://www.airbnb.com/rooms/12345678",
                        "bedrooms": 4,
                        "bathrooms": 3,
                        "accommodates": 10,
                        "annualRevenueUSD": 68420,
                        "occupancyRatePercentage": 52,
                        "averageDailyRateUSD": 361,
                        "distanceMiles": 0.4,
                        "photo_urls": [
                          "https://a0.muscache.com/im/pictures/example/cover.jpg",
                          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
                          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
                        ]
                      }
                    ],
                    "monthlyRentUSD": 2000,
                    "yearOneRentUSD": 24000,
                    "monthlyRevenueUSD": 13432.825977452352,
                    "monthlyExpensesUSD": 2263.6108575197586,
                    "yearOneRevenueUSD": 161193.91172942822,
                    "yearOneOperatingIncomeUSD": 134030.58143919113,
                    "yearOneCashFlowUSD": 110030.58143919116,
                    "yearOneCashOnCashPercentage": 1317.415965507557,
                    "totalCashInvestment": 8352
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "$ref": "#/components/responses/502"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        }
      }
    },
    "/v1/external/analysis/create/owned": {
      "post": {
        "operationId": "createOwnedAnalysis",
        "summary": "Create Owned Analysis",
        "description": "Create an owned-property analysis for a property already in your portfolio. Include mortgage terms to return STR revenue, cash flow, principal paydown, appreciation, and ROI metrics.\n\nAI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.\n\nAI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.\n\nWhen an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.\n\nEach AI step that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI steps that completed, with no base call fee.",
        "tags": [
          "Create analyses"
        ],
        "x-mcp-tool": "create_owned_analysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "description": "Latitude coordinate (must be provided with lng if fullAddress is not used)",
                    "examples": [
                      27.7676
                    ]
                  },
                  "lng": {
                    "type": "number",
                    "description": "Longitude coordinate (must be provided with lat if fullAddress is not used)",
                    "examples": [
                      -82.6403
                    ]
                  },
                  "fullAddress": {
                    "type": "string",
                    "description": "Complete property address (can be used instead of lat/lng coordinates)",
                    "examples": [
                      "4935 2nd Avenue North, St. Petersburg, FL 33703"
                    ]
                  },
                  "purchasePriceUSD": {
                    "type": "number",
                    "description": "Purchase price in USD",
                    "examples": [
                      350000
                    ]
                  },
                  "downPaymentPercentage": {
                    "type": "number",
                    "description": "Down payment percentage (0-40)",
                    "examples": [
                      20
                    ]
                  },
                  "interestRatePercentage": {
                    "type": "number",
                    "description": "Interest rate percentage (0-15)",
                    "examples": [
                      5.1
                    ]
                  },
                  "mortgageLength": {
                    "type": "number",
                    "description": "Mortgage length in years (0-30)",
                    "examples": [
                      30
                    ]
                  },
                  "yearsRemainingOnMortgage": {
                    "type": "number",
                    "description": "Years remaining on mortgage (Can't be higher than mortgage length)"
                  },
                  "bedrooms": {
                    "type": "number",
                    "description": "Number of bedrooms",
                    "examples": [
                      3
                    ]
                  },
                  "bathrooms": {
                    "type": "number",
                    "description": "Number of bathrooms",
                    "examples": [
                      2
                    ]
                  },
                  "accomodates": {
                    "type": "number",
                    "description": "Number of guests the property can accommodate",
                    "examples": [
                      6
                    ]
                  },
                  "monthlyRentUSD": {
                    "type": "number",
                    "description": "Expected monthly rent in USD for long-term rental",
                    "examples": [
                      2500
                    ]
                  },
                  "squareFeet": {
                    "type": "number",
                    "description": "Property square footage",
                    "examples": [
                      1500
                    ]
                  },
                  "state": {
                    "type": "string",
                    "description": "State name",
                    "examples": [
                      "Florida"
                    ]
                  },
                  "city": {
                    "type": "string",
                    "description": "City name",
                    "examples": [
                      "St. Petersburg"
                    ]
                  },
                  "county": {
                    "type": "string",
                    "description": "County name",
                    "examples": [
                      "Pinellas County"
                    ]
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal/ZIP code",
                    "examples": [
                      "33703"
                    ]
                  },
                  "country": {
                    "type": "string",
                    "description": "Country name",
                    "examples": [
                      "United States"
                    ]
                  },
                  "street": {
                    "type": "string",
                    "description": "Street name",
                    "examples": [
                      "2nd Avenue North"
                    ]
                  },
                  "streetNumber": {
                    "type": "string",
                    "description": "Street number",
                    "examples": [
                      "4935"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "description": "Unit/apartment number if applicable"
                  },
                  "addAIComps": {
                    "type": "boolean",
                    "description": "Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.",
                    "examples": [
                      true
                    ]
                  },
                  "addAIExpenseEstimates": {
                    "type": "boolean",
                    "description": "Estimate operating expenses with AI instead of using category defaults",
                    "examples": [
                      true
                    ]
                  }
                },
                "required": [
                  "purchasePriceUSD",
                  "downPaymentPercentage",
                  "interestRatePercentage",
                  "mortgageLength",
                  "yearsRemainingOnMortgage",
                  "bedrooms",
                  "bathrooms",
                  "accomodates"
                ],
                "anyOf": [
                  {
                    "required": [
                      "lat",
                      "lng"
                    ]
                  },
                  {
                    "required": [
                      "fullAddress"
                    ]
                  }
                ]
              },
              "example": {
                "lat": 27.7676,
                "lng": -82.6403,
                "bedrooms": 3,
                "bathrooms": 2,
                "accomodates": 6,
                "purchasePriceUSD": 350000,
                "downPaymentPercentage": 20,
                "interestRatePercentage": 5.1,
                "mortgageLength": 30,
                "yearsRemainingOnMortgage": 30
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Full return metrics for a property you already own: cash flow, ROI, principal paydown, appreciation, percentiles, comparables, and a hosted report URL using your mortgage terms.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "ratePerNightUSD": {
                          "type": "number"
                        },
                        "occupancyRatePercentage": {
                          "type": "number"
                        },
                        "bedrooms": {
                          "type": "number"
                        },
                        "bathrooms": {
                          "type": "number"
                        },
                        "commonSpaces": {
                          "type": "number"
                        },
                        "accomodates": {
                          "type": "number"
                        },
                        "fullAddress": {
                          "type": "string"
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "revenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "adr": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "occupancy": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "quartiles": {
                          "type": "object",
                          "properties": {
                            "25th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "50th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "75th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "90th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "comparables": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "airbnbId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "listingUrl": {
                                "type": "string"
                              },
                              "bedrooms": {
                                "type": "number"
                              },
                              "bathrooms": {
                                "type": "number"
                              },
                              "accommodates": {
                                "type": "number"
                              },
                              "annualRevenueUSD": {
                                "type": "number"
                              },
                              "occupancyRatePercentage": {
                                "type": "number"
                              },
                              "averageDailyRateUSD": {
                                "type": "number"
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "photo_urls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "downPaymentPercentage": {
                          "type": "number"
                        },
                        "mortgageLength": {
                          "type": "number"
                        },
                        "yearsRemainingOnMortgage": {
                          "type": "number"
                        },
                        "interestRatePercentage": {
                          "type": "number"
                        },
                        "propertyTaxPercentage": {
                          "type": "number"
                        },
                        "monthlyRevenueUSD": {
                          "type": "number"
                        },
                        "monthlyExpensesUSD": {
                          "type": "number"
                        },
                        "monthlyTaxesUSD": {
                          "type": "number"
                        },
                        "yearOneRevenueUSD": {
                          "type": "number"
                        },
                        "yearOneOperatingIncomeUSD": {
                          "type": "number"
                        },
                        "yearOneMorgageAndTaxesUSD": {
                          "type": "number"
                        },
                        "yearOneCashFlowUSD": {
                          "type": "number"
                        },
                        "yearOneCashOnCashPercentage": {
                          "type": "number"
                        },
                        "yearOneCapRatePercentage": {
                          "type": "number"
                        },
                        "yearOneReturnOnInvestmentPercentage": {
                          "type": "number"
                        },
                        "yearOnePrincipalPaydownUSD": {
                          "type": "number"
                        },
                        "yearOnePrincipalPaidUSD": {
                          "type": "number"
                        },
                        "yearOneAppreciationUSD": {
                          "type": "number"
                        },
                        "totalCashInvestment": {
                          "type": "number"
                        },
                        "ltrPerMonthUSD": {
                          "type": "number"
                        },
                        "ltrMonthlyExpensesPercentage": {
                          "type": "number"
                        },
                        "revenueBasis": {
                          "type": "string"
                        },
                        "actualAnnualRevenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "average": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "_id": "000000000000000000000000",
                    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
                    "currency": "USD",
                    "ratePerNightUSD": 364.73770491803276,
                    "occupancyRatePercentage": 48,
                    "bedrooms": 4,
                    "bathrooms": 4,
                    "commonSpaces": 1,
                    "accomodates": 12,
                    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
                    "location": {
                      "type": "Point",
                      "coordinates": [
                        -82.6403,
                        27.7676
                      ]
                    },
                    "revenue": {
                      "p25": 48210,
                      "p50": 58440,
                      "p75": 63944.76398163934,
                      "p90": 74280,
                      "avg": 60310
                    },
                    "adr": {
                      "p25": 214,
                      "p50": 288,
                      "p75": 364.73770491803276,
                      "p90": 431,
                      "avg": 318
                    },
                    "occupancy": {
                      "p25": 0.38,
                      "p50": 0.44,
                      "p75": 0.48,
                      "p90": 0.56,
                      "avg": 0.46
                    },
                    "quartiles": {
                      "25th_percentile": {
                        "average_daily_rate": 214,
                        "occupancy_rate": 38,
                        "revenue": 48210
                      },
                      "50th_percentile": {
                        "average_daily_rate": 288,
                        "occupancy_rate": 44,
                        "revenue": 58440
                      },
                      "75th_percentile": {
                        "average_daily_rate": 364.73770491803276,
                        "occupancy_rate": 48,
                        "revenue": 63944.76398163934
                      },
                      "90th_percentile": {
                        "average_daily_rate": 431,
                        "occupancy_rate": 56,
                        "revenue": 74280
                      }
                    },
                    "comparables": [
                      {
                        "airbnbId": "12345678",
                        "name": "Modern 4BR near downtown",
                        "listingUrl": "https://www.airbnb.com/rooms/12345678",
                        "bedrooms": 4,
                        "bathrooms": 3,
                        "accommodates": 10,
                        "annualRevenueUSD": 68420,
                        "occupancyRatePercentage": 52,
                        "averageDailyRateUSD": 361,
                        "distanceMiles": 0.4,
                        "photo_urls": [
                          "https://a0.muscache.com/im/pictures/example/cover.jpg",
                          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
                          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
                        ]
                      }
                    ],
                    "downPaymentPercentage": 20,
                    "mortgageLength": 30,
                    "yearsRemainingOnMortgage": 30,
                    "interestRatePercentage": 5.1,
                    "propertyTaxPercentage": 0.75,
                    "monthlyRevenueUSD": 5328.730331803278,
                    "monthlyExpensesUSD": 1474.1603364983607,
                    "monthlyTaxesUSD": 250,
                    "yearOneRevenueUSD": 63944.76398163934,
                    "yearOneOperatingIncomeUSD": 46254.83994365901,
                    "yearOneMorgageAndTaxesUSD": 21324,
                    "yearOneCashFlowUSD": 24930.83994365901,
                    "yearOneCashOnCashPercentage": 24.86817214984141,
                    "yearOneCapRatePercentage": 11.563709985914752,
                    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
                    "yearOnePrincipalPaydownUSD": 85635.31658640636,
                    "yearOnePrincipalPaidUSD": 5635.31658640636,
                    "yearOneAppreciationUSD": 12000,
                    "totalCashInvestment": 100252,
                    "ltrPerMonthUSD": 1500,
                    "ltrMonthlyExpensesPercentage": 10,
                    "revenueBasis": "full_time_potential",
                    "actualAnnualRevenue": {
                      "p25": 24180,
                      "p50": 36920,
                      "p75": 47350,
                      "p90": 58810,
                      "average": 37640
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "$ref": "#/components/responses/502"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        }
      }
    },
    "/v1/external/analysis/create/cohost": {
      "post": {
        "operationId": "createCohostAnalysis",
        "summary": "Create Cohost Analysis",
        "description": "Create a co-hosting analysis for an owner lead or operator workflow. Return projected STR revenue, co-host commission, host return, and comparable listings.\n\nAI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.\n\nAI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.\n\nWhen an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.\n\nEach AI step that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI steps that completed, with no base call fee.",
        "tags": [
          "Create analyses"
        ],
        "x-mcp-tool": "create_cohost_analysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number",
                    "description": "Latitude coordinate (must be provided with lng if fullAddress is not used)",
                    "examples": [
                      27.7676
                    ]
                  },
                  "lng": {
                    "type": "number",
                    "description": "Longitude coordinate (must be provided with lat if fullAddress is not used)",
                    "examples": [
                      -82.6403
                    ]
                  },
                  "fullAddress": {
                    "type": "string",
                    "description": "Complete property address (can be used instead of lat/lng coordinates)",
                    "examples": [
                      "4935 2nd Avenue North, St. Petersburg, FL 33703"
                    ]
                  },
                  "bedrooms": {
                    "type": "number",
                    "description": "Number of bedrooms",
                    "examples": [
                      3
                    ]
                  },
                  "bathrooms": {
                    "type": "number",
                    "description": "Number of bathrooms",
                    "examples": [
                      2
                    ]
                  },
                  "accomodates": {
                    "type": "number",
                    "description": "Number of guests the property can accommodate",
                    "examples": [
                      6
                    ]
                  },
                  "cohostCommissionPercentage": {
                    "type": "number",
                    "description": "Cohost commission percentage",
                    "examples": [
                      10
                    ]
                  },
                  "squareFeet": {
                    "type": "number",
                    "description": "Property square footage",
                    "examples": [
                      1500
                    ]
                  },
                  "state": {
                    "type": "string",
                    "description": "State name",
                    "examples": [
                      "Florida"
                    ]
                  },
                  "city": {
                    "type": "string",
                    "description": "City name",
                    "examples": [
                      "St. Petersburg"
                    ]
                  },
                  "county": {
                    "type": "string",
                    "description": "County name",
                    "examples": [
                      "Pinellas County"
                    ]
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal/ZIP code",
                    "examples": [
                      "33703"
                    ]
                  },
                  "country": {
                    "type": "string",
                    "description": "Country name",
                    "examples": [
                      "United States"
                    ]
                  },
                  "street": {
                    "type": "string",
                    "description": "Street name",
                    "examples": [
                      "2nd Avenue North"
                    ]
                  },
                  "streetNumber": {
                    "type": "string",
                    "description": "Street number",
                    "examples": [
                      "4935"
                    ]
                  },
                  "unit": {
                    "type": "string",
                    "description": "Unit/apartment number if applicable"
                  },
                  "addAIComps": {
                    "type": "boolean",
                    "description": "Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.",
                    "examples": [
                      true
                    ]
                  },
                  "addAIExpenseEstimates": {
                    "type": "boolean",
                    "description": "Estimate operating expenses with AI instead of using category defaults",
                    "examples": [
                      true
                    ]
                  }
                },
                "required": [
                  "bedrooms",
                  "bathrooms",
                  "accomodates"
                ],
                "anyOf": [
                  {
                    "required": [
                      "lat",
                      "lng"
                    ]
                  },
                  {
                    "required": [
                      "fullAddress"
                    ]
                  }
                ]
              },
              "example": {
                "lat": 27.7676,
                "lng": -82.6403,
                "bedrooms": 3,
                "bathrooms": 2,
                "accomodates": 6
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Projected co-hosting revenue, your commission, net host return, percentiles, comparables, and a hosted report URL.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "ratePerNightUSD": {
                          "type": "number"
                        },
                        "occupancyRatePercentage": {
                          "type": "number"
                        },
                        "bedrooms": {
                          "type": "number"
                        },
                        "bathrooms": {
                          "type": "number"
                        },
                        "commonSpaces": {
                          "type": "number"
                        },
                        "accomodates": {
                          "type": "number"
                        },
                        "fullAddress": {
                          "type": "string"
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "revenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "adr": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "occupancy": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "quartiles": {
                          "type": "object",
                          "properties": {
                            "25th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "50th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "75th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "90th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "comparables": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "airbnbId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "listingUrl": {
                                "type": "string"
                              },
                              "bedrooms": {
                                "type": "number"
                              },
                              "bathrooms": {
                                "type": "number"
                              },
                              "accommodates": {
                                "type": "number"
                              },
                              "annualRevenueUSD": {
                                "type": "number"
                              },
                              "occupancyRatePercentage": {
                                "type": "number"
                              },
                              "averageDailyRateUSD": {
                                "type": "number"
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "photo_urls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "yearOneRevenueUSD": {
                          "type": "number"
                        },
                        "yearOneCohostReturnUSD": {
                          "type": "number"
                        },
                        "yearOneCohostCommissionUSD": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "_id": "000000000000000000000000",
                    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
                    "currency": "USD",
                    "ratePerNightUSD": 364.73770491803276,
                    "occupancyRatePercentage": 48,
                    "bedrooms": 4,
                    "bathrooms": 4,
                    "commonSpaces": 1,
                    "accomodates": 12,
                    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
                    "location": {
                      "type": "Point",
                      "coordinates": [
                        -82.6403,
                        27.7676
                      ]
                    },
                    "revenue": {
                      "p25": 48210,
                      "p50": 58440,
                      "p75": 63944.76398163934,
                      "p90": 74280,
                      "avg": 60310
                    },
                    "adr": {
                      "p25": 214,
                      "p50": 288,
                      "p75": 364.73770491803276,
                      "p90": 431,
                      "avg": 318
                    },
                    "occupancy": {
                      "p25": 0.38,
                      "p50": 0.44,
                      "p75": 0.48,
                      "p90": 0.56,
                      "avg": 0.46
                    },
                    "quartiles": {
                      "25th_percentile": {
                        "average_daily_rate": 214,
                        "occupancy_rate": 38,
                        "revenue": 48210
                      },
                      "50th_percentile": {
                        "average_daily_rate": 288,
                        "occupancy_rate": 44,
                        "revenue": 58440
                      },
                      "75th_percentile": {
                        "average_daily_rate": 364.73770491803276,
                        "occupancy_rate": 48,
                        "revenue": 63944.76398163934
                      },
                      "90th_percentile": {
                        "average_daily_rate": 431,
                        "occupancy_rate": 56,
                        "revenue": 74280
                      }
                    },
                    "comparables": [
                      {
                        "airbnbId": "12345678",
                        "name": "Modern 4BR near downtown",
                        "listingUrl": "https://www.airbnb.com/rooms/12345678",
                        "bedrooms": 4,
                        "bathrooms": 3,
                        "accommodates": 10,
                        "annualRevenueUSD": 68420,
                        "occupancyRatePercentage": 52,
                        "averageDailyRateUSD": 361,
                        "distanceMiles": 0.4,
                        "photo_urls": [
                          "https://a0.muscache.com/im/pictures/example/cover.jpg",
                          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
                          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
                        ]
                      }
                    ],
                    "yearOneRevenueUSD": 161193.91172942825,
                    "yearOneCohostReturnUSD": 116059.61644518835,
                    "yearOneCohostCommissionUSD": 32238.78234588565
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "$ref": "#/components/responses/502"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        }
      }
    },
    "/v1/external/analysis/enhance": {
      "post": {
        "operationId": "enhanceAnalysisWithAi",
        "summary": "Enhance Analysis with AI",
        "description": "Runs AI enrichment against an analysis you already created and returns the recalculated analysis. Use this when you want AI-selected comparables or AI expense estimates applied after the fact, or when you would rather keep the original create call fast.\n\nAI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.\n\nAI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.\n\nWhen an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.\n\nEach AI step that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI steps that completed, with no base call fee.\n\nIf every AI step you requested fails, the call is free and the response contains only warnings, with no data. Your stored analysis is unchanged in that case, so the copy you already have is still current. Create endpoints always return data, because their base fee covers the report itself.",
        "tags": [
          "AI enrichment"
        ],
        "x-mcp-tool": "enhance_analysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "analysisId": {
                    "type": "string",
                    "description": "The _id of an analysis previously created with your API key",
                    "examples": [
                      "000000000000000000000000"
                    ]
                  },
                  "addAIComps": {
                    "type": "boolean",
                    "description": "Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.",
                    "examples": [
                      true
                    ]
                  },
                  "addAIExpenseEstimates": {
                    "type": "boolean",
                    "description": "Estimate operating expenses with AI instead of using category defaults",
                    "examples": [
                      true
                    ]
                  }
                },
                "required": [
                  "analysisId"
                ]
              },
              "example": {
                "analysisId": "000000000000000000000000",
                "addAIComps": true,
                "addAIExpenseEstimates": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The full analysis with AI results applied and every financial metric recalculated, plus an aiComps summary and any non-fatal warnings.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "ratePerNightUSD": {
                          "type": "number"
                        },
                        "occupancyRatePercentage": {
                          "type": "number"
                        },
                        "bedrooms": {
                          "type": "number"
                        },
                        "bathrooms": {
                          "type": "number"
                        },
                        "commonSpaces": {
                          "type": "number"
                        },
                        "accomodates": {
                          "type": "number"
                        },
                        "fullAddress": {
                          "type": "string"
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "revenue": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "adr": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "occupancy": {
                          "type": "object",
                          "properties": {
                            "p25": {
                              "type": "number"
                            },
                            "p50": {
                              "type": "number"
                            },
                            "p75": {
                              "type": "number"
                            },
                            "p90": {
                              "type": "number"
                            },
                            "avg": {
                              "type": "number"
                            }
                          }
                        },
                        "quartiles": {
                          "type": "object",
                          "properties": {
                            "25th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "50th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "75th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            },
                            "90th_percentile": {
                              "type": "object",
                              "properties": {
                                "average_daily_rate": {
                                  "type": "number"
                                },
                                "occupancy_rate": {
                                  "type": "number"
                                },
                                "revenue": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        },
                        "comparables": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "airbnbId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "listingUrl": {
                                "type": "string"
                              },
                              "bedrooms": {
                                "type": "number"
                              },
                              "bathrooms": {
                                "type": "number"
                              },
                              "accommodates": {
                                "type": "number"
                              },
                              "annualRevenueUSD": {
                                "type": "number"
                              },
                              "occupancyRatePercentage": {
                                "type": "number"
                              },
                              "averageDailyRateUSD": {
                                "type": "number"
                              },
                              "distanceMiles": {
                                "type": "number"
                              },
                              "photo_urls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "propertyTaxPercentage": {
                          "type": "number"
                        },
                        "internetAndTVUSD": {
                          "type": "number"
                        },
                        "waterUSD": {
                          "type": "number"
                        },
                        "electricUSD": {
                          "type": "number"
                        },
                        "propertyInsuranceUSD": {
                          "type": "number"
                        },
                        "HOAUSD": {
                          "type": "number"
                        },
                        "repairsUSD": {
                          "type": "number"
                        },
                        "suppliesUSD": {
                          "type": "number"
                        },
                        "cleaningCostPercentage": {
                          "type": "number"
                        },
                        "monthlyRevenueUSD": {
                          "type": "number"
                        },
                        "monthlyExpensesUSD": {
                          "type": "number"
                        },
                        "yearOneRevenueUSD": {
                          "type": "number"
                        },
                        "yearOneCashFlowUSD": {
                          "type": "number"
                        },
                        "yearOneCashOnCashPercentage": {
                          "type": "number"
                        }
                      }
                    },
                    "aiComps": {
                      "type": "object",
                      "properties": {
                        "selectedCompIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "benchmark": {
                          "type": "object",
                          "properties": {
                            "annualRevenueUSD": {
                              "type": "number"
                            },
                            "ratePerNightUSD": {
                              "type": "number"
                            },
                            "occupancyRatePercentage": {
                              "type": "number"
                            }
                          }
                        },
                        "rationale": {
                          "type": "string"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {}
                        },
                        "applied": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "_id": "000000000000000000000000",
                    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
                    "currency": "USD",
                    "ratePerNightUSD": 364.73770491803276,
                    "occupancyRatePercentage": 48,
                    "bedrooms": 4,
                    "bathrooms": 4,
                    "commonSpaces": 1,
                    "accomodates": 12,
                    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
                    "location": {
                      "type": "Point",
                      "coordinates": [
                        -82.6403,
                        27.7676
                      ]
                    },
                    "revenue": {
                      "p25": 48210,
                      "p50": 58440,
                      "p75": 63944.76398163934,
                      "p90": 74280,
                      "avg": 60310
                    },
                    "adr": {
                      "p25": 214,
                      "p50": 288,
                      "p75": 364.73770491803276,
                      "p90": 431,
                      "avg": 318
                    },
                    "occupancy": {
                      "p25": 0.38,
                      "p50": 0.44,
                      "p75": 0.48,
                      "p90": 0.56,
                      "avg": 0.46
                    },
                    "quartiles": {
                      "25th_percentile": {
                        "average_daily_rate": 214,
                        "occupancy_rate": 38,
                        "revenue": 48210
                      },
                      "50th_percentile": {
                        "average_daily_rate": 288,
                        "occupancy_rate": 44,
                        "revenue": 58440
                      },
                      "75th_percentile": {
                        "average_daily_rate": 364.73770491803276,
                        "occupancy_rate": 48,
                        "revenue": 63944.76398163934
                      },
                      "90th_percentile": {
                        "average_daily_rate": 431,
                        "occupancy_rate": 56,
                        "revenue": 74280
                      }
                    },
                    "comparables": [
                      {
                        "airbnbId": "12345678",
                        "name": "Modern 4BR near downtown",
                        "listingUrl": "https://www.airbnb.com/rooms/12345678",
                        "bedrooms": 4,
                        "bathrooms": 3,
                        "accommodates": 10,
                        "annualRevenueUSD": 68420,
                        "occupancyRatePercentage": 52,
                        "averageDailyRateUSD": 361,
                        "distanceMiles": 0.4,
                        "photo_urls": [
                          "https://a0.muscache.com/im/pictures/example/cover.jpg",
                          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
                          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
                        ]
                      }
                    ],
                    "propertyTaxPercentage": 0.75,
                    "internetAndTVUSD": 90,
                    "waterUSD": 85,
                    "electricUSD": 180,
                    "propertyInsuranceUSD": 210,
                    "HOAUSD": 0,
                    "repairsUSD": 125,
                    "suppliesUSD": 60,
                    "cleaningCostPercentage": 8.5,
                    "monthlyRevenueUSD": 5328.730331803278,
                    "monthlyExpensesUSD": 1474.1603364983607,
                    "yearOneRevenueUSD": 63944.76398163934,
                    "yearOneCashFlowUSD": 24930.83994365901,
                    "yearOneCashOnCashPercentage": 24.86817214984141
                  },
                  "aiComps": {
                    "selectedCompIds": [
                      "12345678",
                      "23456789"
                    ],
                    "benchmark": {
                      "annualRevenueUSD": 63944.76398163934,
                      "ratePerNightUSD": 364.73770491803276,
                      "occupancyRatePercentage": 48
                    },
                    "rationale": "Selected comparables matching bedroom count, pool and waterfront access.",
                    "warnings": [],
                    "applied": true
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "502": {
            "$ref": "#/components/responses/502"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-bnbcalc-api-key",
        "description": "All API requests require authentication using an API key. API keys are tied to your BNBCalc account, should be kept server-side, and should never be exposed in frontend code. Include your API key in the request header as shown below:"
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Limit": {
        "description": "Requests allowed in the current window.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Reset": {
        "description": "When the current window resets.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "statusCode": {
            "type": "integer"
          },
          "message": {
            "description": "A message, or one message per invalid field.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        },
        "required": [
          "success",
          "statusCode",
          "message"
        ]
      }
    },
    "responses": {
      "400": {
        "description": "Bad Request - Invalid parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "401": {
        "description": "Unauthorized - Invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "402": {
        "description": "Payment Required - The key's account has no active API subscription, or no Listing Optimizer credits are left",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "403": {
        "description": "Forbidden - The analysis does not belong to your API key, or AI estimates are disabled",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "404": {
        "description": "Not Found - The requested analysis, listing or location was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "409": {
        "description": "Conflict - An AI or Listing Optimizer run is already in progress, the analysis changed since you read it, or the report is not ready yet",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "429": {
        "description": "Too Many Requests - External API route limit exceeded",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "500": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "502": {
        "description": "Bad Gateway - The AI model returned an unusable response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "503": {
        "description": "Service Unavailable - An AI model or listing source is temporarily unavailable; try again later",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
