Skip to content

About

Pequi API — Colombia's First Real Estate Data API. SDK, MCP server, and documentation.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Pequi

Typing SVG

Colombia's First Real Estate Data API
API publica de datos inmobiliarios — Ibague (64 barrios) + Bogota (212 barrios)
Open Finance · Decreto 0368

Website TypeScript SDK PyPI MCP Server
License Status Base c402 Open Finance Ibagué Bogotá Endpoints


Table of Contents


What it is

Colombia's first public real estate data API — built on Open Finance (Decreto 0368). Search properties, query neighborhoods with estratos, get reference prices per m², valuate properties with AVM, and access live financial indicators (UVR/IPC) from Banco de la Republica.

29 live endpoints (the tables below list 34; five documented routes currently return 404 — see Publishing status):

Capability Endpoints Auth
Properties & neighborhoods (276 barrios, 2 cities) GET /api/v1/properties GET /api/v1/barrios Free
Price benchmarks & AVM valuation GET /api/v1/benchmarks POST /api/v1/avm POST /api/v1/avm/bulk Free/Key
Live UVR, IPC, Ley 820 rent adjustment GET /api/v1/uvr GET /api/v1/ipc POST /api/v1/rent-increase Free
Bogotá UPZ (117) & cadastral valuation GET /api/v1/bogota/upz GET /api/v1/bogota/cadastral Free
Mortgage rates (34 products, 10 banks) GET /api/v1/mortgage-rates Free
Geocoding (address → coordinates) GET /api/v1/geocode Free
Contract generation & Wompi payments POST /api/v1/contracts POST /api/v1/payments API Key
Bank verification (Prometeo Open Finance) POST /api/v1/bank-verification API Key
AI chat with streaming SSE POST /api/v1/chat API Key
Prepaid credits (c402) & subscriptions GET /api/v1/credits POST /api/v1/credits/purchase POST /api/v1/subscriptions/api-checkout API Key
Complexes (Ley 675/2001) GET /api/v1/complexes GET /api/v1/complexes/{slug} GET /api/v1/complexes/{slug}/units Free
Schedule visits POST /api/v1/visits API Key
Upload files POST /api/v1/upload API Key
Monitoring & usage GET /api/v1/monitoring/* (latency, errors, uptime, usage) API Key
c402 monetization — HTTP 402 Payment Required GET /api/v1/credits POST /api/v1/credits/purchase Free

Architecture

flowchart LR
    subgraph Clients
        A[AI agent / MCP client]
        B[TypeScript SDK]
        C[Python SDK]
        D[curl / Postman]
    end

    subgraph "xpequi.xyz — Next.js 16"
        E[/api/v1/* REST/]
        F[c402 middleware<br/>HTTP 402 challenge]
        G[API key + scope auth]
    end

    subgraph Data
        H[(Neon PostgreSQL 17)]
        I[BanRep: UVR / IPC]
        J[IGAC cadastral + UPZ]
        K[Superfinanciera mortgage rates]
    end

    subgraph Payments
        L[Wompi<br/>PSE / Nequi / card]
        M[Prometeo<br/>Open Finance]
    end

    A --> E
    B --> E
    C --> E
    D --> E
    E --> G --> F
    F -->|credits| H
    E --> H
    E --> I
    E --> J
    E --> K
    F --> L
    E --> M
Loading

Endpoints overview

All endpoints live under https://xpequi.xyz/api/v1/. Full request/response schemas: docs/api/openapi.yaml (OpenAPI 3.0.3, importable into Postman).

Properties & Neighborhoods

Method Endpoint Description Auth
GET /api/v1/properties Search properties with filters (city, type, price, bedrooms, estrato) —
GET /api/v1/barrios 64 barrios Ibagué · 212 barrios Bogotá with estrato and GIS —
GET /api/v1/benchmarks Reference prices per m² by neighborhood and type —
GET /api/v1/geocode Address → coordinates (OpenStreetMap Nominatim) —
POST /api/v1/avm Automated valuation with comparable properties —
POST /api/v1/avm/bulk Batch AVM (up to 100 properties, idempotency-supported) —

Financial Indicators

Method Endpoint Description Auth
GET /api/v1/uvr Current UVR — Banco de la República (live via MCP) —
GET /api/v1/ipc Annual IPC inflation — for Ley 820 rent adjustments —
POST /api/v1/rent-increase Calculate legal rent increase per Ley 820 —
GET /api/v1/mortgage-rates 34 mortgage products from 10 Colombian banks —

Bogotá

Method Endpoint Description Auth
GET /api/v1/bogota/upz Bogotá UPZ units (117) — land use, TransMilenio —
GET /api/v1/bogota/cadastral IGAC cadastral reference values by localidad + estrato —

Contracts & Payments

Method Endpoint Description Auth
POST /api/v1/contracts Generate Ley 820 rental contract API Key
GET /api/v1/contracts/{id} Retrieve a generated contract API Key
POST /api/v1/payments Create Wompi payment (PSE, Nequi, Daviplata, card) API Key
GET /api/v1/payments/{id} Check payment status API Key

Complexes (Conjuntos Residenciales)

Method Endpoint Description Auth
GET /api/v1/complexes List residential complexes —
GET /api/v1/complexes/{slug} Complex details (amenities, units, images) —
GET /api/v1/complexes/{slug}/units Individual units within a complex —

AI & Communication

Method Endpoint Description Auth
POST /api/v1/chat AI real estate assistant (streaming SSE) API Key
POST /api/v1/visits Schedule property visit API Key
POST /api/v1/upload Upload files (max 5MB, images/docs) API Key
POST /api/v1/bank-verification Verify Colombian bank accounts (Prometeo Open Finance) API Key

c402 Monetization

Method Endpoint Description Auth
GET /api/v1/credits Prepaid credit balance and pack pricing —
POST /api/v1/credits/purchase Buy credit pack via Wompi API Key
POST /api/v1/subscriptions/api-checkout Monthly subscription (AGENTE/CONJUNTO) API Key

Monitoring

Method Endpoint Description Auth
GET /api/v1/monitoring/usage Hourly call count, credits remaining, current tier API Key
GET /api/v1/monitoring/latency P50/P95/P99 latency per endpoint API Key
GET /api/v1/monitoring/errors 4xx/5xx breakdown per endpoint API Key
GET /api/v1/monitoring/uptime API availability over window API Key

Webhooks

Method Endpoint Description Auth
POST /api/v1/webhooks/endpoints Create webhook (HMAC-SHA256 signed) API Key
GET /api/v1/webhooks/endpoints List registered webhooks API Key
DELETE /api/v1/webhooks/endpoints/{id} Unregister webhook API Key
POST /api/v1/webhooks/endpoints/{id}/test Test webhook delivery API Key

c402 monetization

Pequi implements the c402 Protocol — a Colombian-first HTTP 402 Payment Required pattern for API monetization, payments via Wompi in COP (no crypto, no wallets).

Rate limits & tiers

Tier Price Limits Buy
FREE $0/mes 30 req/min · 150 req/day —
PREPAGO (c402) Desde $2,500 COP 50/200/1000 prepaid calls /precios
AGENTE API $30K COP/mes 100 req/min · 1,000 req/day /precios
CONJUNTO API $150K COP/mes 300 req/min · 5,000 req/day /precios
ENTERPRISE Custom Custom Contacto

How it works

  1. FREE tier gets 30 req/min, 150 req/day — no API key needed for GET endpoints
  2. When exceeded → HTTP 402 Payment Required with X-402-Challenge header
  3. The challenge contains a Wompi checkout URL (PSE, Nequi, Daviplata, credit card)
  4. After payment, credits auto-activate — retry with your API key

Security model: SHA-256 webhook verification · UUID v4 single-use nonces · Postgres-transactional credit deduction (credit_ledger + append-only credit_transactions, conditional UPDATE … WHERE balance > 0) · 24h idempotency guard · Zero crypto (no blockchain, no wallets, no RSA)

Buy without an API key:

  1. Go to /precios
  2. Click "COMPRAR →" on your tier
  3. Sign in with your Pequi account (self-hosted auth — email and password; Clerk was removed in June 2026)
  4. Pay via Wompi — credits/tier activate automatically
{
  "error": "payment_required",
  "message": "Has excedido tu límite gratuito. Paga por más llamadas API.",
  "code": "PAYMENT_REQUIRED",
  "recoverable": true,
  "suggestedAction": "Compra créditos prepago o suscríbete en https://xpequi.xyz/precios",
  "c402": {
    "nonce": "550e8400-...",
    "amount": 2500,
    "currency": "COP",
    "calls": 50,
    "paymentUrl": "https://checkout.wompi.co/p/?",
    "expiresAt": "2026-05-15T22:00:00Z"
  }
}

Full protocol details: c402 — pagos agénticos sin crypto


SDKs

Publishing status — verified 2026-11-17. Only the Python package is on a public registry. pequi-api-client, pequi-mcp-server and pequi-opencode-plugin are not published to npm (all three return 404), and the JSR and GHCR artefacts do not resolve either. Install those from this repository until the releases are published. Commands below that say npx or npm install will fail today.

Package Install Description Status
TypeScript SDK npm install pequi-api-client 31 methods · full type safety · every endpoint
Python SDK pip install pequi-api-client 16 sub-APIs · fluent interface · minimal deps
MCP Server from this repo: packages/mcp-server (npm run build && node dist/index.js) 10 tools · protocol 2025-11-25 · Claude Desktop, Cursor, Copilot
OpenClaw Plugin packages/openclaw-plugin/ Hermes agent gateway (archived — OpenClaw removed from stack May 2026)
Ollama Tool packages/ollama-tool/ Local LLM property search via Ollama
OpenCode Plugin opencode plugin install pequi-opencode-plugin Agent plugin for OpenCode

TypeScript SDK

Full type safety with 31 methods covering every API endpoint. Install from npm:

npm install pequi-api-client
import { PequiClient, PequiApiError } from 'pequi-api-client'

const client = new PequiClient({ apiKey: *** })

// ── Search properties ──────────────────────────────────────
const properties = await client.searchProperties({
  city: 'ibague',
  tipo: 'apartamento',
  barrio: 'centro',
  minPrice: 100_000_000,
  maxPrice: 500_000_000,
  limit: 10,
})

// ── Neighborhood data ──────────────────────────────────────
const barrios = await client.getBarrios('bogota')

// ── Price benchmarks ───────────────────────────────────────
const benchmarks = await client.getBenchmarks({
  barrio: 'centro',
  tipo: 'apartamento',
})

// ── Geocoding ──────────────────────────────────────────────
const coords = await client.geocode('Calle 10 #3-15, Ibagué')

// ── AVM (Automated Valuation) ──────────────────────────────
const avm = await client.getAVM({
  area: 80,
  bedrooms: 3,
  bathrooms: 2,
  propertyType: 'APARTMENT',
  barrio: 'centro',
  city: 'ibague',
})

// ── Financial indicators ───────────────────────────────────
const uvr = await client.getUVR()
const ipc = await client.getIPC()
const rentIncrease = await client.calculateRentIncrease({
  currentRent: 1_200_000,
  startDate: '2025-05-01',
  months: 12,
})

// ── Contracts (Ley 820) ────────────────────────────────────
const contract = await client.generateContract({
  landlordName: 'María García',
  landlordCedula: '123456789',
  tenantName: 'Juan Pérez',
  tenantCedula: '987654321',
  propertyAddress: 'Calle 10 #3-15, Ibagué',
  rentAmount: 1_200_000,
  startDate: '2026-06-01',
  endDate: '2028-05-31',
})

// ── c402 Credits & Subscriptions ───────────────────────────
const balance = await client.getCredits()
const checkout = await client.purchaseCredits(200)     // 200 calls
const sub = await client.getSubscriptionCheckout('AGENTE') // $30K/mo

// ── Payments ───────────────────────────────────────────────
const payment = await client.createPayment({
  userId: 'user_xxx',
  amount: 1200000,
  paymentType: 'RENT',
})

// ── Monitoring ─────────────────────────────────────────────
const usage = await client.getUsage()
const latency = await client.getLatency('p95')
const errors = await client.getErrors()
const uptime = await client.getUptime('24h')

// ── Error handling ─────────────────────────────────────────
try {
  const props = await client.searchProperties({ city: 'invalid' })
} catch (err) {
  if (err instanceof PequiApiError) {
    switch (err.code) {
      case 'RATE_LIMIT_EXCEEDED':
      case 'PAYMENT_REQUIRED':
        console.log(`⏳ Wait ${err.retryAfter}s or buy credits`)
        break
      case 'INVALID_API_KEY':
        console.log('🔑 Get a key at https://xpequi.xyz/developers')
        break
      default:
        console.log(`❌ ${err.code}: ${err.message}`)
    }
  }
}

Python SDK

Fluent sub-API design. Minimal dependencies (urllib3, python-dateutil, certifi):

Version skew — verified 2026-11-17. pip install pequi-api-client currently installs 0.1.0, while packages/python-sdk in this repository is 0.3.1. The published 0.1.0 exposes 7 sub-APIs and has no PequiApiError, so the example below (written against 0.3.1) will fail on import until 0.3.1 is published. Install from the repository for the current API:

pip install ./packages/python-sdk
pip install pequi-api-client
from pequi_api_client import PequiClient, PequiApiError

client = PequiClient(api_key="pk_live_...")

# Fluent sub-API design — each domain is a property
properties = client.properties.search(city="ibague", limit=5)
barrios = client.barrios.list(city="bogota")
benchmarks = client.benchmarks.list(barrio="centro")
coords = client.geocode.geocode("Calle 10 #3-15, Ibagué")

# Financial indicators
uvr = client.finance.get_uvr()
ipc = client.finance.get_ipc()
increase = client.finance.calculate_rent_increase(
    current_rent=1200000, start_date="2025-05-01"
)

# AVM valuation
avm = client.avm.estimate(
    area=80, bedrooms=3, bathrooms=2,
    property_type="APARTMENT", barrio="centro", city="ibague"
)

# c402 credits
balance = client.credits.balance()
checkout = client.credits.purchase(calls=200)

# Monitoring
usage = client.monitoring.usage()
uptime = client.monitoring.uptime(window="24h")

# Error handling
try:
    client.properties.search(city="invalid")
except PequiApiError as e:
    print(e.status, e.code, e.message)

Installation channels

1. npm (recommended)

# SDK
npm install pequi-api-client

# MCP server (Claude, Cursor, Copilot)
node packages/mcp-server/dist/index.js

2. JSR

npx jsr add @pequi/api-client

3. Docker (MCP server)

docker pull ghcr.io/mcpvot/pequi-mcp-server
docker run -p 3100:3100 ghcr.io/mcpvot/pequi-mcp-server

4. Direct from GitHub (no registry)

{
  "mcpServers": {
    "pequi": {
      "command": "npx",
      "args": ["github:MCPVOT/xpequi-api/packages/mcp-server"]
    }
  }
}

Quickstart

No API key needed for GET endpoints. Three commands, zero setup:

# Search properties in Bogota
curl https://xpequi.xyz/api/v1/properties?city=bogota&limit=3

# Neighborhoods with estratos
curl https://xpequi.xyz/api/v1/barrios?city=ibague

# Live UVR from Banco de la Republica
curl https://xpequi.xyz/api/v1/uvr

# IPC inflation - Ley 820 rent adjustment
curl https://xpequi.xyz/api/v1/ipc

Or with the TypeScript SDK:

import { PequiClient } from 'pequi-api-client'

const client = new PequiClient()
const properties = await client.searchProperties({ city: 'bogota', limit: 5 })

No API key needed for GET endpoints (properties, barrios, benchmarks, geocode, UVR, IPC, complexes). Only write operations require authentication. Get your free API key →


API reference

Authentication

Most public GET endpoints work without authentication. Write endpoints require a Bearer token:

Authorization: Bearer pk_liv...f456

Get your API key from the Developer Portal. API keys are SHA-256 hashed at rest and scoped to specific tiers.

Tier limits by key

Scope Without Key With FREE Key With AGENTE Key With CONJUNTO Key
Properties ✅ Read ✅ Read ✅ Read ✅ Read
Barrios ✅ Read ✅ Read ✅ Read ✅ Read
Contracts ❌ ❌ ✅ Write ✅ Write
Payments ❌ ❌ ❌ ✅ Write
Webhooks ❌ ❌ ✅ CRUD ✅ CRUD

Error handling

All errors return a standardized envelope that both human developers and AI agents can parse deterministically:

{
  "error": "API key inválida.",
  "code": "INVALID_API_KEY",
  "recoverable": false,
  "suggestedAction": "Verifica tu API key en https://xpequi.xyz/developers",
  "retryAfter": null,
  "requestId": "req_a1b2c3d4"
}

Error codes

Code HTTP Meaning Recoverable
INVALID_API_KEY 401 Missing or malformed Bearer token ❌
INSUFFICIENT_SCOPE 403 Key doesn't have access to this endpoint ❌
NOT_FOUND 404 Resource not found ❌
RATE_LIMIT_EXCEEDED 429 Too many requests — check retryAfter ✅
PAYMENT_REQUIRED 402 FREE tier exceeded — buy credits (see c402) ✅
QUOTA_EXCEEDED 429 Daily subscription limit reached ✅
BAD_REQUEST 400 Invalid input — check the error message ❌
VALIDATION_ERROR 422 Zod schema validation failed ❌
INTERNAL_ERROR 500 Server error — contact support ❌
SERVICE_UNAVAILABLE 503 Upstream provider down — retry later ✅

Agent tip: Use recoverable to decide whether to retry. Use retryAfter (seconds) for backoff.

Pagination

Endpoints that return lists support cursor-based pagination:

curl "https://xpequi.xyz/api/v1/properties?city=ibague&limit=20&page=1"

Parameters: limit (max 100, default 20), page (1-indexed, default 1).

The response includes a meta object with pagination info where available.

Response format

All API responses follow a consistent structure:

✅ Success:
{
  "data": { ... },        // The requested resource or list
  "meta": {                // Optional pagination metadata
    "total": 150,
    "page": 1,
    "limit": 20,
    "pages": 8
  }
}

❌ Error:
{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "recoverable": true|false,
  "suggestedAction": "What the user should do",
  "retryAfter": 30,        // seconds (only for 429)
  "requestId": "req_abc"   // for support
}

MCP server

MCP discovery: .well-known/mcp in this repo · MCP Directory | Smithery | Mintlify

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pequi": {
      "command": "npx",
      "args": ["-y", "pequi-mcp-server"]
    }
  }
}

Available MCP tools (10)

Tool Description
search_properties Search properties with filters (city, type, price, estrato, bedrooms)
get_barrios Get neighborhoods with estrato and GIS coordinates (Ibagué + Bogotá)
get_benchmarks Reference prices per m² by neighborhood
geocode Geocode Colombian addresses
get_uvr Current UVR from Banco de la República
get_ipc Annual IPC inflation for Ley 820 adjustments
calculate_rent_increase Calculate legal rent increase
get_upzs Bogotá UPZ boundaries — 117 units, land use, TransMilenio
get_cadastral_valuation IGAC cadastral reference values by localidad+estrato
get_mortgage_rates 34 mortgage products from 10 Colombian banks

AI agent integration

Available inside every major AI assistant and coding agent:

Agent How to Connect Install
Claude Desktop MCP Server node packages/mcp-server/dist/index.js
Claude Code MCP config docs/claude-code-integration.md
Cursor MCP Server node packages/mcp-server/dist/index.js
VS Code Copilot MCP Server node packages/mcp-server/dist/index.js
ChatGPT Custom GPT Action docs/api/custom-gpt/gpt-action.json
Perplexity MCP Server node packages/mcp-server/dist/index.js
Z.AI (GLM-5.1) MCP Server npx -y robertcprice/glm-mcp-server
Qwen 3.6 Plus MCP Server npx -y @iflow-mcp/gy920-qwen-mcp-tool
OpenRouter MCP Server npx -y @stabgan/openrouter-mcp-multimodal
OpenCode Plugin opencode plugin install pequi-opencode-plugin
Ollama Custom Tool packages/ollama-tool/pequi_tool.py
OpenClaw Gateway Plugin packages/openclaw-plugin/pequi-gateway.js

All agents use the same /api/v1/ endpoints. No API key needed for FREE tier (30 req/min).


Docs & links


License

MIT © Pequi — Built for Colombia's real estate ecosystem 🇨🇴

About

Pequi API — Colombia's First Real Estate Data API. SDK, MCP server, and documentation.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages