# Cobroker API — CRE Tools for AI Agents

> Full documentation index: https://cobroker.ai/llms-full.txt
> OpenAPI spec: https://cobroker.ai/.well-known/openapi.yaml
> MCP discovery: https://cobroker.ai/.well-known/mcp.json

## What is Cobroker?
Cobroker provides a REST API that gives AI agents commercial real estate (CRE) capabilities.
Any AI agent can create projects, manage properties, enrich data with demographics,
search for places and businesses, and run AI-powered research — all via HTTP.

## Base URL
https://app.cobroker.ai/api/agent/openclaw

## Authentication
All requests require two headers:
- X-Agent-User-Id: your agent user ID
- X-Agent-Secret: your agent secret key
- Content-Type: application/json

## Capabilities
- Projects: Full CRUD for CRE projects with properties, custom fields, and map views
- Properties: Add, update, delete properties with automatic geocoding from addresses
- Demographics & Psychographics: ESRI GeoEnrichment data by radius, drive-time, or walk-time:
  - Core Demographics: total population, median age, total households, population density, household size, daytime population
  - Income: median household income, per capita income, average household income, disposable income, income brackets ($25K to $250K+)
  - Employment: total employment, retail jobs, healthcare jobs, office jobs, food service, manufacturing, construction, education, unemployment rate
  - Housing: median home value, median rent, owner-occupied, renter-occupied, vacant units, housing built after 2010, median year built
  - Age Groups: age 0-4, 5-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65-74, 75+, working age population
  - Race/Ethnicity: white, black, hispanic, asian, two or more races, diversity index
  - Tapestry Segmentation: 67 psychographic lifestyle segments (e.g., "Laptops and Lattes", "Metro Renters", "Savvy Suburbanites"), top 3 segments per area, LifeMode group, segment median income/age
  - Consumer Spending: restaurant, retail, entertainment, apparel, grocery, healthcare spending — total expenditures + Spending Potential Index (100 = national avg)
  - Market Potential Index (MPI): propensity scores for dining, shopping, fitness, financial products, internet/media usage
  - Business Data: business counts, employee counts, sales volume by NAICS sector (retail trade, food service, healthcare, professional services, real estate)
  - Crime Indexes: total crime, personal crime, property crime, murder, robbery, burglary, larceny, motor vehicle theft — relative risk scores (100 = national avg)
  - Retail Marketplace: supply vs demand gap analysis by NAICS — total retail demand, food & beverage, clothing, general merchandise, restaurants, grocery
  - Commute: average commute time, drive alone %, public transit %, work from home %, carpool %
  - Education: bachelor's degree %, graduate degree %, high school diploma %, educational attainment
  - Health Insurance: employer-insured, uninsured, Medicare, Medicaid rates by age group
- Location Intelligence: Foot traffic and visitor analytics for commercial properties:
  - Visitation: estimated visits, daily/hourly traffic patterns, visit trends, visit frequency
  - Dwell Time: visitor duration segments, engagement depth analysis
  - Trade Area: true trade area from visitor origins by Census Block Group, drive-time trade areas
  - Competitive: property rankings, competitive benchmarking, nearby activity analysis
  - Retail Sales: transaction volume, average ticket size, sales trends, daily revenue estimates
  - Visitor Journey: cross-shopping behavior, favorite chains, visitor origin analysis
- AI Enrichment: Ask any research question about each property — zoning, building details, market data. Four processor tiers (base ~15s, core ~1-5min, pro ~3-9min, ultra ~5-25min)
- Places Search: Find existing businesses, chains, and locations via Google Places API. Preview before saving. Nationwide region search up to 400 results
- Nearby Analysis: Analyze what surrounds each property — find nearest business or count place types within a radius
- Map Layers: Pin brand logos on project maps with colored markers

## Endpoints
All paths relative to https://app.cobroker.ai/api/agent/openclaw

GET    /projects                          — List all projects
POST   /projects                          — Create project with properties and custom fields
GET    /projects/{id}                     — Get project details including properties and field values
PATCH  /projects/{id}                     — Update project name, description, or visibility
DELETE /projects/{id}                     — Delete project and all associated data
POST   /projects/{id}/properties          — Add properties to existing project
PATCH  /projects/{id}/properties          — Update property addresses or field values
DELETE /projects/{id}/properties          — Remove properties by ID
GET    /projects/{id}/demographics        — List all 58 available demographic types
POST   /projects/{id}/demographics        — Add ESRI demographic data to properties
POST   /projects/{id}/enrichment          — Submit AI research enrichment (async)
GET    /projects/{id}/enrichment          — Check enrichment status and results
POST   /projects/{id}/places/search       — Search Google Places and save as properties or map layer
POST   /projects/{id}/places/nearby       — Analyze nearby places for each property

## Quick Start

### Create a project with properties
```
curl -X POST "https://app.cobroker.ai/api/agent/openclaw/projects" \
  -H "Content-Type: application/json" \
  -H "X-Agent-User-Id: YOUR_USER_ID" \
  -H "X-Agent-Secret: YOUR_SECRET" \
  -d '{
    "name": "Dallas Warehouses",
    "description": "Q1 industrial survey",
    "public": true,
    "properties": [
      {
        "address": "123 Main St, Dallas, TX 75201",
        "fields": { "Price": "$500,000", "Size": "10,000 SF", "Type": "Warehouse" }
      }
    ]
  }'
```

### Add demographics to a project
```
curl -X POST "https://app.cobroker.ai/api/agent/openclaw/projects/{projectId}/demographics" \
  -H "Content-Type: application/json" \
  -H "X-Agent-User-Id: YOUR_USER_ID" \
  -H "X-Agent-Secret: YOUR_SECRET" \
  -d '{ "dataType": "population", "radius": 1, "mode": "radius" }'
```

### Search for places
```
curl -X POST "https://app.cobroker.ai/api/agent/openclaw/projects/new/places/search" \
  -H "Content-Type: application/json" \
  -H "X-Agent-User-Id: YOUR_USER_ID" \
  -H "X-Agent-Secret: YOUR_SECRET" \
  -d '{ "query": "Starbucks in Dallas", "preview": true }'
```

### AI research enrichment
```
curl -X POST "https://app.cobroker.ai/api/agent/openclaw/projects/{projectId}/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-Agent-User-Id: YOUR_USER_ID" \
  -H "X-Agent-Secret: YOUR_SECRET" \
  -d '{
    "prompt": "What is the zoning classification for this property?",
    "columnName": "Zoning",
    "processor": "core"
  }'
```

## Response Format
All responses return JSON with a `success` boolean. Project creation returns `projectId`, `publicUrl`, `propertyCount`, and `columns`. Property operations return counts. Demographics and enrichment return column metadata.

## Address Format
Addresses must have at least 3 comma-separated components: street, city, state+zip.
Example: "123 Main St, Dallas, TX 75201"

## Constraints
- Maximum 50 properties per request
- Properties are auto-geocoded from addresses
- Demographics require properties with coordinates
- Enrichment is async — poll the status endpoint for results
- Places search supports up to 400 results with regionSearch: true

## OpenClaw Integration
Cobroker is available as an OpenClaw skill. Install the cobroker-projects skill to give your OpenClaw agent full CRE capabilities — projects, demographics, places, traffic, and AI research.
- Integration guide: https://cobroker.ai/openclaw
- Skill name: cobroker-projects
- Requires: COBROKER_AGENT_USER_ID, COBROKER_AGENT_SECRET environment variables

## Coming Soon
- CLI: Command-line interface for Cobroker API (install via npm/pip)
- Python SDK: Native Python client library
- TypeScript SDK: Native TypeScript/Node.js client library

## Links
- API Page: https://cobroker.ai/developers
- OpenAPI Spec: https://cobroker.ai/.well-known/openapi.yaml
- Get Started: https://app.cobroker.ai/signup
- Main Website: https://cobroker.ai