ColoCompass

Developers

Build on the ColoCompass API

Give your application or AI agent direct access to the ColoCompass catalog: search verified datacenter data, match requirements against every listed location and register leads 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: Authorization: Bearer cc_…. Keys are shown once at creation, can be revoked instantly, and carry one or more scopes:

  • catalog:readSearch the catalog and fetch individual datacenter profiles.
  • matchRun requirement profiles through the matching pipeline for a ranked shortlist.
  • leads:writeRegister requests 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

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", "completeness_score": 86 },
      "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–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 — search_datacenters, get_datacenter, match_requirements, submit_lead — with the same API keys, scopes and rate limits.

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 verified catalog as the website — nothing more. Datacenter ids are stable public identifiers. Match scores reflect technical fit only: paid plans reward data quality, never a higher position in results.

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’ll set you up.

Request API access

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