Getting Started

Cobroker API Documentation

Cobroker provides a REST API that gives AI agents commercial real estate capabilities. Create projects, manage properties, enrich with ESRI demographics and Tapestry psychographics, analyze foot traffic, search Google Places, and run AI-powered research — all via HTTP.

Authentication

Every request requires two headers. No OAuth, no token refresh — just two static headers on every call.

# Required headers on every request
X-Agent-User-Id: your-user-id
X-Agent-Secret: your-secret
Content-Type: application/json

Quick Start

Create a project with properties in one call:

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",
    "public": true,
    "properties": [
      {
        "address": "123 Main St, Dallas, TX 75201",
        "fields": { "Price": "$500,000", "Size": "10,000 SF" }
      }
    ]
  }'

Response:

{
  "success": true,
  "projectId": "uuid",
  "publicUrl": "https://app.cobroker.ai/public/uuid",
  "propertyCount": 1,
  "geocodedCount": 1,
  "columns": [{ "id": "uuid", "name": "Price" }, { "id": "uuid", "name": "Size" }]
}

Projects & Properties

Create a Project

Create a new project with properties and custom fields. Properties are automatically geocoded from addresses. Maximum 50 properties per request.

{
  "name": "Dallas Warehouses",
  "description": "Q1 industrial survey",
  "source": "openclaw",
  "public": true,
  "properties": [
    {
      "address": "123 Main St, Dallas, TX 75201",
      "fields": {
        "Price": "$500,000",
        "Size": "10,000 SF",
        "Type": "Warehouse"
      }
    }
  ]
}

List / Get Projects

Returns all projects with name, description, property count, and URLs.

Returns full project details including all properties, columns, and field values. Field names are human-readable (not UUIDs).

Add Properties

Add properties to an existing project. New field names automatically create new columns. Existing field names map to existing columns.

{
  "properties": [
    {
      "address": "456 Oak Ave, Dallas, TX 75202",
      "fields": { "Price": "$750K", "Size": "15,000 SF" }
    }
  ]
}

Update / Delete

Update project name, description, or visibility. Only provided fields are updated.

Update property addresses or field values. Property id is required. Address changes trigger re-geocoding.

Delete project and all associated data.

Remove properties by ID.

Demographics & Psychographics

Overview

Enrich properties with ESRI GeoEnrichment data. 15+ categories covering demographics, psychographics, consumer spending, crime, business data, and more. Each data type can be queried by radius (miles), drive-time (minutes), or walk-time (minutes). Properties must have coordinates (geocoded from addresses).

Available Data Types

Returns all available data types grouped by category.

Add Demographics

{
  "dataType": "population",
  "radius": 1,
  "mode": "radius"
}

Parameters:

• dataType — demographic metric (see list above)
• radius — 0.1 to 100 (miles for radius, minutes for drive/walk)
• mode — "radius" | "drive" | "walk" (default: "radius")
• columnName — optional, auto-generated if omitted

Foot Traffic

Overview

Location intelligence data for commercial properties. Foot traffic counts, dwell time, trade area analysis, competitive rankings, retail sales estimates, and visitor journey data — derived from mobile location signals.

Available Metrics

Get Traffic Data

{
  "dataType": "visits",
  "period": "last_12_months",
  "granularity": "monthly"
}

Parameters:

• dataType — traffic metric (see list above)
• period — last_month, last_3_months, last_6_months, last_12_months
• granularity — daily, weekly, monthly

Places Search

Search Places

Search Google Places for existing businesses, chains, and locations. Preview before saving. Use projectId: "new" to auto-create a project.

// Preview mode — returns results without saving
{ "query": "Starbucks in Dallas", "preview": true }

// Save to new project
{ "query": "Starbucks in Dallas", "projectName": "Starbucks Dallas" }

// Save to existing project
// POST /projects/{existingId}/places/search
{ "query": "Starbucks in Dallas" }

Parameters:

• query — search text
• preview — if true, returns without saving (default: false)
• maxResults — max 400 (default: 50)
• regionSearch — search across 7 US regions for nationwide coverage

Nearby Analysis

Analyze what's near each property. Two modes:

// Nearest mode — find closest matching place
{ "query": "grocery store", "radiusMiles": 2, "mode": "nearest" }

// Count mode — count place types within radius
{ "placeTypes": ["restaurant", "cafe"], "radiusMiles": 1, "mode": "count" }

Map Layers

Save places as a map layer with brand logos instead of project properties:

{
  "query": "Starbucks",
  "destination": "layer",
  "layerName": "Starbucks Locations",
  "markerColor": "#00704A"
}

AI Research

Submit Enrichment

Ask any question about each property. The API researches the answer using web sources and returns structured results. Async — returns immediately, poll for results.

{
  "prompt": "What is the zoning classification for this property?",
  "columnName": "Zoning",
  "processor": "core"
}

Processor tiers:

• base — fast, ~15–100s per property
• core — balanced (default), ~1–5min
• pro — thorough, ~3–9min
• ultra — exhaustive, ~5–25min

Poll for Results

Poll every ~30 seconds. When status is "complete", fetch project details to read the enrichment column values.

curl -X GET "https://app.cobroker.ai/api/agent/openclaw/projects/{id}/enrichment?columnId={columnId}" \
  -H "X-Agent-User-Id: your-user-id" \
  -H "X-Agent-Secret: your-secret"

Integrations

OpenClaw Skill

Install the cobroker-projects skill in your OpenClaw agent. Requires COBROKER_AGENT_USER_ID and COBROKER_AGENT_SECRET environment variables.

Full OpenClaw integration guide →

Download skill file →

MCP Server

Cobroker publishes an MCP discovery file for automatic integration with Claude Code, Cursor, and other MCP clients.

View MCP config →

CLI Coming Soon

Command-line interface for the Cobroker API. Install via npm or pip. Manage projects, run enrichments, and search places from your terminal.

Knowledge Base

FAQ

Address Format

Addresses must have at least 3 comma-separated components:

Constraints & Limits

• Maximum 50 properties per create/add request
• Places search: 50 results default, up to 400 with regionSearch
• Properties are auto-geocoded from addresses
• Demographics require properties with coordinates
• Enrichment is async — poll status endpoint for results
• Map layers require an existing project
• Duplicate layer names return 409
• Always create projects as public: true for shareable URLs

Response Format

All responses are JSON with a top-level success boolean.

// Success response
{ "success": true, "projectId": "uuid", "publicUrl": "..." }

// Error response
{ "success": false, "message": "Description of the error" }

• Project creation returns: projectId, publicUrl, propertyCount, columns
• Property operations return counts
• Demographics and enrichment return column metadata
• Enrichment submit returns 202 with columnId for polling