{
  "openapi": "3.1.0",
  "info": {
    "title": "cf0 public API",
    "version": "1.0.0",
    "summary": "Find homes to rent that cf0 lists.",
    "description": "cf0 is an AI-native real estate agency. This read-only API finds homes to rent on cf0. It needs no key. Each IP can make 120 reads each minute. Errors are JSON with an `error` code. To act for a person (list a home, give Zero a task), use the MCP server at https://api.cf0.ai/mcp. See https://cf0.ai/developers and https://cf0.ai/auth.md.",
    "contact": {
      "name": "cf0",
      "email": "luca@cf0.ai",
      "url": "https://cf0.ai/developers"
    },
    "termsOfService": "https://cf0.ai/terms"
  },
  "servers": [
    {
      "url": "https://cf0.ai",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "cf0 developer resources",
    "url": "https://cf0.ai/developers"
  },
  "security": [],
  "tags": [
    {
      "name": "homes",
      "description": "Homes to rent"
    }
  ],
  "paths": {
    "/api/public/listings": {
      "get": {
        "operationId": "searchHomes",
        "tags": [
          "homes"
        ],
        "summary": "Search homes to rent",
        "description": "Returns up to 24 homes to rent that match the filters, and a cursor for the next page. Use when a person wants a home to rent in a market or city.",
        "parameters": [
          {
            "name": "market",
            "in": "query",
            "required": false,
            "description": "Market code, for example MT or US-FL.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}(?:-[A-Za-z0-9]{1,8})?$"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "City slug from GET /api/public/listings/places, for example st-pauls-bay.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "beds",
            "in": "query",
            "required": false,
            "description": "Minimum number of bedrooms.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            }
          },
          {
            "name": "max_rent_minor",
            "in": "query",
            "required": false,
            "description": "Maximum monthly rent in the minor unit of the market currency.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 99999999
            }
          },
          {
            "name": "available_by",
            "in": "query",
            "required": false,
            "description": "Latest move-in date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Order of the results.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "rent_asc",
                "rent_desc"
              ],
              "default": "newest"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The next_cursor value from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of homes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "homes",
                    "next_cursor"
                  ],
                  "properties": {
                    "homes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/HomeCard"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Send as cursor for the next page. Null on the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/listings/markets": {
      "get": {
        "operationId": "listMarkets",
        "tags": [
          "homes"
        ],
        "summary": "List markets",
        "description": "Returns each market where owners can list homes on cf0, with its rent currency and area unit.",
        "responses": {
          "200": {
            "description": "Markets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "markets"
                  ],
                  "properties": {
                    "markets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "code",
                          "country",
                          "rent_currency",
                          "area_unit"
                        ],
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          },
                          "subdivision": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "rent_currency": {
                            "type": "string"
                          },
                          "fee_currency": {
                            "type": "string"
                          },
                          "area_unit": {
                            "type": "string",
                            "enum": [
                              "m2",
                              "ft2"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/listings/places": {
      "get": {
        "operationId": "listPlaces",
        "tags": [
          "homes"
        ],
        "summary": "List places with homes",
        "description": "Returns each city that has homes to rent now, with the number of homes and the lowest rent.",
        "parameters": [
          {
            "name": "market",
            "in": "query",
            "required": false,
            "description": "Only places in this market.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Places.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "places"
                  ],
                  "properties": {
                    "places": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "market_code",
                          "city_slug",
                          "homes"
                        ],
                        "properties": {
                          "market_code": {
                            "type": "string"
                          },
                          "city_slug": {
                            "type": "string"
                          },
                          "homes": {
                            "type": "integer"
                          },
                          "unit_count": {
                            "type": "integer"
                          },
                          "lowest_rent": {
                            "$ref": "#/components/schemas/Money"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/listings/homes/{market}/{city}/{home}": {
      "get": {
        "operationId": "getHome",
        "tags": [
          "homes"
        ],
        "summary": "Read one home",
        "description": "Returns the full listing of one home: facts, photos, deposit, terms, units and showing hours. The three path parts come from the path field of a home card.",
        "parameters": [
          {
            "name": "market",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "mt"
          },
          {
            "name": "city",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "st-pauls-bay"
          },
          {
            "name": "home",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3-bedroom-41b05d22"
          }
        ],
        "responses": {
          "200": {
            "description": "The home.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Home"
                }
              }
            }
          },
          "404": {
            "description": "No listed home has this path. The body is {\"error\":\"home_not_found\"}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/public/listings/photos/{mediaId}": {
      "get": {
        "operationId": "getHomePhoto",
        "tags": [
          "homes"
        ],
        "summary": "Get a home photo",
        "description": "Returns one photo of a listed home as an image.",
        "parameters": [
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The photo.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "No photo has this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Money": {
        "type": "object",
        "required": [
          "amount_minor",
          "currency",
          "minor_exponent"
        ],
        "properties": {
          "amount_minor": {
            "type": "integer",
            "description": "Amount in the minor unit of the currency, for example cents."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code.",
            "example": "EUR"
          },
          "minor_exponent": {
            "type": "integer",
            "description": "Number of decimal places of the currency.",
            "example": 2
          }
        }
      },
      "HomeCard": {
        "type": "object",
        "required": [
          "home_id",
          "path",
          "title",
          "market_code",
          "city_slug",
          "bedrooms",
          "bathrooms",
          "rent",
          "available_from",
          "available_count"
        ],
        "properties": {
          "home_id": {
            "type": "string",
            "format": "uuid"
          },
          "path": {
            "type": "string",
            "description": "Path of the home page on cf0.ai. Add .md for a markdown version.",
            "example": "/homes/mt/st-pauls-bay/3-bedroom-41b05d22"
          },
          "title": {
            "type": "string"
          },
          "building_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "market_code": {
            "type": "string",
            "description": "Market code: ISO 3166-1 alpha-2, with an optional subdivision.",
            "example": "MT"
          },
          "city_slug": {
            "type": "string",
            "example": "st-pauls-bay"
          },
          "bedrooms": {
            "type": "integer",
            "minimum": 0
          },
          "bathrooms": {
            "type": "number",
            "minimum": 0
          },
          "furnished": {
            "type": "string",
            "example": "furnished"
          },
          "floor_area_m2": {
            "type": [
              "number",
              "null"
            ]
          },
          "area_unit": {
            "type": "string",
            "enum": [
              "m2",
              "ft2"
            ],
            "description": "Unit that people in this market use for floor area."
          },
          "rent": {
            "$ref": "#/components/schemas/Money",
            "description": "Monthly rent. For a building with more units, the lowest rent."
          },
          "rent_high": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": "null"
              }
            ]
          },
          "available_from": {
            "type": "string",
            "format": "date"
          },
          "available_count": {
            "type": "integer",
            "description": "Number of units with this layout that are available."
          },
          "cover_photo_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Use with GET /api/public/listings/photos/{mediaId}."
          },
          "amenities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "lat",
                  "lng",
                  "precision"
                ],
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  },
                  "precision": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Home": {
        "allOf": [
          {
            "$ref": "#/components/schemas/HomeCard"
          },
          {
            "type": "object",
            "properties": {
              "public_address_line": {
                "type": "string"
              },
              "postal_area": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "deposit": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Money"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "min_term_months": {
                "type": "integer"
              },
              "max_term_months": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "photos": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "room": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "floor_plan_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "facts": {
                "type": "array",
                "description": "Facts that the owner wrote about the home.",
                "items": {
                  "type": "object",
                  "required": [
                    "topic",
                    "body"
                  ],
                  "properties": {
                    "topic": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              },
              "advertiser_name": {
                "type": "string"
              },
              "ownership_verified": {
                "type": "boolean",
                "const": true,
                "description": "A person at cf0 checked the proof of ownership."
              },
              "viewing_call_listing_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When set, a renter can view the home on a live call with Zero."
              },
              "application_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "tour": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "The 3D tour of the home. Open it on cf0.ai with ?model=1 on the home page.",
                    "required": [
                      "format",
                      "bundle_path",
                      "same_floor_plan",
                      "rooms"
                    ],
                    "properties": {
                      "format": {
                        "type": "string",
                        "enum": [
                          "plan"
                        ]
                      },
                      "bundle_path": {
                        "type": "string",
                        "description": "Storage path of the tour bundle."
                      },
                      "same_floor_plan": {
                        "type": "boolean",
                        "description": "The tour and the floor plan show the same layout."
                      },
                      "rooms": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "room_key",
                            "label",
                            "position",
                            "target",
                            "fov"
                          ],
                          "properties": {
                            "room_key": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "position": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              },
                              "minItems": 3,
                              "maxItems": 3,
                              "description": "x, y and z in metres."
                            },
                            "target": {
                              "type": "array",
                              "items": {
                                "type": "number"
                              },
                              "minItems": 3,
                              "maxItems": 3,
                              "description": "x, y and z in metres."
                            },
                            "fov": {
                              "type": "number",
                              "description": "Field of view in degrees."
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "units": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "floor": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "available_from": {
                      "type": "string",
                      "format": "date"
                    },
                    "rent": {
                      "$ref": "#/components/schemas/Money"
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              },
              "showing_hours": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "timezone": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "weekday": {
                              "type": "integer"
                            },
                            "opens_minute": {
                              "type": "integer"
                            },
                            "closes_minute": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "confirmed_at": {
                "type": "integer",
                "description": "Unix time in milliseconds when the owner last confirmed the listing."
              }
            },
            "additionalProperties": true
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable error code, for example invalid_beds, home_not_found or rate_limited."
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A parameter is not valid. The error code names it, for example invalid_beds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "More than 120 reads in one minute from this IP. Wait, then try again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "rate_limited"
            }
          }
        }
      }
    }
  }
}