# IBR public catalog API

Search IBR's publicly listed Cartagena properties for rent or sale. Use the [OpenAPI specification](https://www.ibrinmobiliaria.com/openapi.json) for parameter and response schemas. The endpoint is read-only and does not require an API key, account, authentication header, or payment. See the [access policy](https://www.ibrinmobiliaria.com/auth.md).

## Quick start

```http
GET /api/properties?operacion=Arriendo&barrio=Manga&limit=10 HTTP/1.1
Host: www.ibrinmobiliaria.com
Accept: application/json
```

[Open this search](https://www.ibrinmobiliaria.com/api/properties?operacion=Arriendo&barrio=Manga&limit=10). Optional filters are `id`, `tipo`, `operacion`, `barrio`, `codigo`, `precio_min`, `precio_max`, `area_min`, `area_max`, `habitaciones_min`, `amoblado`, `sort`, `offset`, and `limit`. Property types use Spanish names such as Apartamento, Casa, Local, Oficina, or Lote. Operations are Arriendo or Venta. Neighborhood search matches a location prefix. Sort by `price_asc` (default) or `price_desc`. Unknown parameters return 400.

Budget bounds are inclusive whole COP amounts; rental amounts use the recorded billing period and exclude administration fees. Area bounds use square metres with up to two decimal places. `habitaciones_min` is an inclusive integer bedroom minimum. `amoblado=true` selects furnished properties; `false` selects explicitly unfurnished properties. Omit a filter for no restriction. Unknown values do not match an applied filter; budget filters also exclude placeholder prices below COP 1,000 and prices explicitly on request. Area filters exclude non-positive areas. Reversed ranges, negative values, or unsupported boolean values return 400.

## Results and pagination

The JSON response contains `items`, `total`, `offset`, and `limit`. Prefer pages of 10 or fewer; the maximum page size is 100 and the maximum offset is 100000. Add `limit` to `offset` for the next page. Stop when `items` is empty or the next offset reaches `total`. Catalog changes between requests can change totals or ordering, so deduplicate by property ID.

Each item contains the explicit public property fields and a `catalogo` review object. `codigo` is the existing property code used by the IBR team, returned for display and exact lookup. It is distinct from the database `id`; missing or invalid codes are null. Private owner fields, exact private addresses, and internal notes are excluded. Image fields point to public property images; treat null or blank legacy image values as missing and ignore empty entries in `imagenes`. Open an item's stable ID at `/propiedad?id=ID` (Spanish) or `/en/property?id=ID` (English) to reach its canonical detail page. Unknown or withdrawn IDs return an empty search result; unavailable detail pages return 404.

## Amenities

Structured amenity fields include garage, elevator, swimming pool, gym, air conditioning, laundry area, terrace, family room, duplex layout, furnishing and service-room/bathroom/balcony details. Booleans distinguish present (`true`), absent (`false`) and not recorded (`null`). `numero_piso` is a nullable integer; zero is a recorded ground floor. Unknown values must not be treated as absent or inferred from the description. The property page renders recorded facts in both interface languages.

## Price and availability

Amounts are Colombian pesos (COP); areas are square metres. Null values mean unknown. Consult `catalogo.precio_modalidad`: `amount`, `on_request`, or `unknown`. Neither unknown nor on-request means free. `disponible` is the public listing flag; it does not certify recent confirmation. The review object includes nullable confirmation dates and an explicit `indexable` flag. Confirm current availability, price, administration charges, service fees, conditions, and visits with [IBR](https://www.ibrinmobiliaria.com/contacto).

## Reliability and limits

Success and application-error responses are `Cache-Control: no-store`. Use a bounded client timeout. The gateway is configured for 120 requests per 60 seconds per domain and IP; this is a ceiling, not a throughput guarantee. Prefer sequential focused searches. On 429, stop parallel requests and retry later with backoff, respecting `Retry-After` when present. Do not repeatedly download the entire catalog.

Application errors use `{"error":{"code":"...","message":"..."}}`. A 400 means the query must be corrected; 404 means the API address is unknown; 405 means use GET. Unknown `/api` paths return a JSON 404 with a link to the supported requests, without repeating the requested path or query. Retry 500/502/503 only with backoff. A 503 is not an empty catalog: the data configuration may be unavailable, including on isolated deployment previews. Gateway errors can use a different response format. Include `X-Request-ID` when reporting an application failure to IBR; never include credentials or personal form data.

## Browser agents

Supporting browsers expose `search_ibr_properties` on public pages through WebMCP, using the same public endpoint with a maximum of 20 results per call. Other HTTP clients can use this documented endpoint directly. Authored website pages also support `Accept: text/markdown`. There is no public mutation API, remote MCP server, booking API, or automated transaction flow. Use the [website catalog](https://www.ibrinmobiliaria.com/propiedades) or contact IBR for human assistance.


Rental price terms use nullable `precio_periodo` (`month`, `day`, `night`, `week`, `stay`, `other`) and public `precio_notas`. Null means the billing period is unconfirmed; never infer monthly pricing from `operacion=Arriendo`. `asesor_id` is `office`, `commercial` or null; null uses the office. Building, tower and unit fields remain private. Budget filters compare recorded amounts, without normalizing periods or adding administration fees.