ColoCompass

Developers

Build on the ColoCompass API

Give your application or AI agent direct access to the ColoCompass catalog: search datacenter data, match requirements against every listed location and register inquiries for your clients, over a simple JSON API.

Request API accessOpenAPI 3.1 spec

Authentication

Every request carries an API key in the Authorization header. Keys are shown once at creation, can be revoked instantly, and carry one or more scopes.

Authorization: Bearer cc_…
catalog:read
Search the catalog and fetch individual datacenter profiles.
match
Run requirement profiles through the matching pipeline for a ranked shortlist.
leads:write
Register inquiries on behalf of an end customer, with their explicit consent.

Rate limits: 300 requests per 10 minutes per key by default (configurable per client); lead submissions are additionally capped at 10 per hour. Requests beyond the limit return status 429.

Endpoints

Four endpoints cover search, a single profile, matching and inquiries.

GET/api/v1/datacenterscatalog:read

Search the catalog

Search verified locations with the same criteria as the on-site discovery search: country, metro, capacity, rack density, tier, certifications, cooling and more. Paginated with total/limit/offset.

Request

curl -H "Authorization: Bearer cc_YOUR_KEY" \
  "https://colocompass.com/api/v1/datacenters?country=NL&capacityKw=500&limit=2"

Response

{
  "total": 42,
  "limit": 2,
  "offset": 0,
  "data": [
    {
      "id": "loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f",
      "name": "Amsterdam 1",
      "operator": { "name": "Example Operator", "verification_status": "operator_verified" },
      "location": { "city": "Amsterdam", "country": "NL", "metro_region": "Amsterdam" },
      "specs": { "uptime_tier": "tier_3", "max_rack_density_kw": 20, "certifications": ["iso_27001"] },
      "availability": { "status": "available", "lifecycle_stage": "operational" },
      "data_quality": { "verification_status": "operator_verified" },
      "profile_url": "https://colocompass.com/datacenter/loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f"
    }
  ]
}
GET/api/v1/datacenters/{id}catalog:read

Fetch one datacenter

Fetch a single location by the public id returned from search or match. Ids are stable public keys; internal identifiers are never exposed.

Request

curl -H "Authorization: Bearer cc_YOUR_KEY" \
  "https://colocompass.com/api/v1/datacenters/loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f"

Response

{
  "data": { "id": "loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f", "name": "Amsterdam 1", "...": "..." }
}
POST/api/v1/matchmatch

Match requirements

Run a requirement profile through the same matching pipeline as the on-site search: a hard criteria filter plus a technical fit score (0 to 100). When nothing passes every hard criterion, the closest alternatives are returned with used_fallback set to true. The score reflects technical fit only; it is never influenced by commercial plans. Optional free_text_requirements adds semantic annotation (similarity per match plus unranked suggestions) without ever changing the ranking.

Request

curl -X POST "https://colocompass.com/api/v1/match" \
  -H "Authorization: Bearer cc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {
      "capacity_kw": 500,
      "desired_rack_density_kw": 20,
      "location_text": "Amsterdam",
      "distance_km": 50
    },
    "limit": 5
  }'

Response

{
  "used_fallback": false,
  "matches": [
    {
      "id": "loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f",
      "name": "Amsterdam 1",
      "operator": "Example Operator",
      "score": 70,
      "match_label": "Good candidate",
      "match_reasons": ["Fits the requested capacity", "Rack density meets the desired 20 kW"],
      "verification_status": "operator_verified",
      "facts": { "power": "Total power band 5–20 MW" },
      "profile_url": "https://colocompass.com/datacenter/loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f"
    }
  ]
}
POST/api/v1/leadsleads:write

Submit a lead

Register a request for up to 5 datacenters on behalf of an end customer, with their explicit consent. The request follows exactly the same lead flow as the public request form, and one lead always follows one handling route: self_managed (direct to the operator, verified listings only) or guided (independent guidance).

Request

curl -X POST "https://colocompass.com/api/v1/leads" \
  -H "Authorization: Bearer cc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_name": "Jane Smith",
    "contact_email": "jane@client-company.com",
    "company_name": "Client Company BV",
    "handling_route": "guided",
    "workload_summary": "500 kW GPU cluster, 20 kW per rack, Amsterdam metro, live Q1 2027.",
    "datacenter_ids": ["loc-2f7e0a1c-4b3d-4e2a-9c8d-1a2b3c4d5e6f"],
    "end_customer_consent": true
  }'

Response

{ "reference_code": "RFQ-7K2M9QX4" }

MCP for AI agents

AI agents can use the ColoCompass API natively through the Model Context Protocol. The MCP server exposes the same functionality as the REST endpoints as tools, with the same API keys, scopes and rate limits.

Tools

  • search_datacenters
  • get_datacenter
  • match_requirements
  • submit_lead

Endpoint (streamable HTTP, POST only)

https://colocompass.com/api/v1/mcp

Example client configuration

{
  "mcpServers": {
    "colocompass": {
      "type": "http",
      "url": "https://colocompass.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer cc_YOUR_KEY" }
    }
  }
}

Good to know

The API reads exactly the same catalog as the website, nothing more. Datacenter ids are stable public identifiers. Match scores reflect technical fit only: results are based on the requirements, and operators cannot buy their position.

The machine-readable contract lives at /api/v1/openapi.json, generated from the same code that serves the endpoints.

Getting access

API keys are issued personally after a short API agreement that covers fair use of the data. Tell us what you want to build and we will set you up.

Request API access

Working with clients as an adviser or reseller? See what ColoCompass offers partners.