{"openapi":"3.1.0","info":{"title":"DC Hub \u2014 Data Center Intelligence API","version":"2.12.21","description":"DC Hub provides real-time data center intelligence: facility search (24,800+ distinct facilities, 170+ countries), M&A deal tracking, construction pipeline data, energy pricing, and site scoring.","contact":{"name":"DC Hub Support","url":"https://dchub.cloud","email":"info@dchub.cloud"},"termsOfService":"https://dchub.cloud/terms","license":{"name":"CC-BY-4.0 for DCPI scores + methodology; other layers per DATA-LICENSE.md","url":"https://dchub.cloud/data-sources"},"x-dchub-envelope":"1.0"},"servers":[{"url":"https://dchub.cloud","description":"Production"}],"paths":{"/api/v1/keys/claim":{"post":{"operationId":"claimFreeKey","summary":"Mint a free DC Hub API key (no email, no account)","description":"Returns a working API key in one POST \u2014 no email, no browser, no signup. Pass it as the X-API-Key header on any keyed endpoint. Call this FIRST when a keyed endpoint answers 402 or 403; those responses carry the same instruction inline.\n\nIdempotent per (client_name, source IP) inside the reuse window: the same client_name from the same IP gets the SAME key back with reused=true, and a different client_name mints a new one. Send a client_name that is distinct per agent or per end user \u2014 a single constant sent from a shared egress IP collapses every caller onto one key and one quota.\n\n\u2605 The free unbound-call allowance is metered per SOURCE IP, not per client_name or per key, and it carries across re-mints \u2014 a fresh client_name does NOT reset it. So callers sharing one egress IP share one allowance, and every key minted after it is spent arrives already gated with bind_email_required. Binding an operator email (free, via the bind_email tool or POST /api/v1/keys/identify) lifts that gate and keeps the free tier. Hosted integrations that proxy many end users through one IP should bind an email per end user rather than rely on the unbound allowance.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","maxLength":80,"description":"Who is calling \u2014 distinct per agent or end user, e.g. 'acme-corp/workspace-42'. Also the idempotency key."},"intended_use":{"type":"string","maxLength":400,"description":"Optional free text; telemetry only, never gates the key."},"email":{"type":"string","description":"Optional. Makes the key recoverable later via recover_my_key; omit and you still get a key instantly."}}}}}},"responses":{"200":{"description":"Key issued. Always carries ok, api_key, tier, usage_instructions, upgrade_url and free_tier_summary. When the source IP has already spent its unbound calls the body ALSO carries bind_required=true, gate='bind_email_required', free_calls_unbound and a note \u2014 the key is real but the next validate refuses it until an email is bound. Check for `gate` before assuming the key is unrestricted."},"429":{"description":"This source IP is inside the claim rate limit"},"503":{"description":"Minting unavailable; the body names the email-verified fallback"}},"tags":["Public"]}},"/api/v1/facilities/{facility_id}":{"get":{"operationId":"getFacilityDetail","summary":"One facility's record","description":"Look up a single facility by the `id` or `slug` that searchFacilities returns. The response shape is decided by the caller's tier. Anonymous: id, name, city, state, country, status, slug, plus coordinates rounded to 2 decimal places (~1.1 km) and an `_upgrade` block. A free claimed key adds provider, operator, market and region at the same precision, plus exact coordinates and street address for up to 10 distinct facilities a month: a call for a new facility spends one, re-reading one is free, the allowance is shared with the website and MCP, and `_location_allowance` reports what was spent and what remains. A Starter key returns the full record at 2 decimal places with the same monthly exact-location allowance. A Developer or Pro key returns the full record: exact coordinates, power_mw, address and source, and no `_upgrade`. Branch on `_upgrade` being present rather than on whether you sent a key \u2014 a free key still carries it. `_coord_precision_dp` states the rounding applied (null when exact), so never treat a returned coordinate as exact without checking it.","parameters":[{"name":"facility_id","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric id (e.g. 8484) or slug (e.g. lumen-technologies-level-3-ashburn-23a0d3a2); searchFacilities returns both on every row"}],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Facility record \u2014 basic preview plus _upgrade for anonymous and free callers, full record for Developer/Pro"},"404":{"description":"No facility with that id or slug"}},"tags":["Public"]}},"/api/v1/stats":{"get":{"operationId":"getStats","summary":"Platform statistics","description":"Returns global stats: total facilities, countries, providers, capacity (MW)","responses":{"200":{"description":"Platform statistics"}},"tags":["Public"]}},"/api/v1/interconnection-queue/refined":{"get":{"operationId":"getRefinedQueue","summary":"Server-side set-reduction over the ISO interconnection queue","description":"Filters ~5,300 US interconnection-queue projects (7 ISOs) server-side so an agent ingests survivors, not the raw ~1,744 GW queue (avoids in-context-filter token blowup). Predicates: min_mw, max_ttp_months (ISO-level estimate), iso (comma union), baseload_only, fuel_type, and the Phase-2 spatial predicates max_fiber_km + geocoded_only. Returns the DCHubEnvelope with _entity=queue_results; ~83% of survivors carry lat/lng + a compact per-survivor site_evaluation_handoff (ready-to-pipe analyze_site + get_water_risk args).","parameters":[{"name":"min_mw","in":"query","schema":{"type":"number"},"description":"Minimum project capacity in MW (e.g. 1000 for 1 GW+)"},{"name":"max_ttp_months","in":"query","schema":{"type":"integer"},"description":"Max time-to-power in months (ISO-level avg interconnection wait; keeps projects in ISOs at or under this)"},{"name":"iso","in":"query","schema":{"type":"string"},"description":"Restrict to one or more ISOs (comma-separated union), from PJM/ERCOT/MISO/CAISO/SPP/NYISO/ISO-NE. e.g. iso=ERCOT,PJM. Hyphens are normalized (ISONE == ISO-NE). Combines with max_ttp_months as an intersection."},{"name":"baseload_only","in":"query","schema":{"type":"boolean","default":false},"description":"Keep only firm/dispatchable fuel; exclude wind/solar/storage. (Firm/intermittent split only \u2014 does NOT sub-divide peaker vs combined-cycle gas; the queue has no duty-cycle field.)"},{"name":"fuel_type","in":"query","schema":{"type":"string"},"description":"Inclusive substring match on the raw fuel label; comma/semicolon separated for a union (e.g. 'gas' hits GAS/Natural Gas, 'nuclear,hydro' unions both). Use to isolate a specific generation class server-side instead of post-filtering in context."},{"name":"status","in":"query","schema":{"type":"string","default":"active"},"description":"Queue status filter. Default 'active' = still progressing (excludes withdrawn/cancelled/suspended/in-commercial-operation) \u2014 cross-ISO safe, since SPP labels live projects 'IA FULLY EXECUTED/ON SCHEDULE' etc. rather than 'active'. 'all' = no filter; any other value = literal substring match."},{"name":"max_fiber_km","in":"query","schema":{"type":"number"},"description":"Keep only survivors within this many km of the nearest MAPPED long-haul fiber route endpoint (coarse backbone proximity from a sparse ~260-node dataset, over a county-centroid origin \u2014 NOT last-mile fiber distance). Implies geocoded rows only."},{"name":"geocoded_only","in":"query","schema":{"type":"boolean","default":false},"description":"Keep only survivors that carry lat/lng (~83% of the queue) \u2014 i.e. those an agent can pipe straight into analyze_site via the site_evaluation_handoff."},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":1000},"description":"Max survivors returned"}],"responses":{"200":{"description":"Refined queue survivors (_entity=queue_results)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/analyze-parcel":{"post":{"operationId":"analyzeParcel","summary":"Structured read of a GeoJSON parcel boundary (Phase 3)","description":"Geodesic acreage + largest-member centroid as representative_point (never the multi-part center) + contiguous flag + per-member breakdown + a site_evaluation_handoff, for any GeoJSON Polygon/MultiPolygon. Reads any polygon you pass; DC Hub does not yet own parcel boundaries, so get_refined_queue survivors do not auto-carry geometry. Returns the DCHubEnvelope with _entity=parcel_analysis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["geometry"],"properties":{"geometry":{"type":"object","description":"GeoJSON Polygon or MultiPolygon parcel boundary"},"capacity_mw":{"type":"number","description":"Optional target load in MW, passed into the handoff"}}}}}},"responses":{"200":{"description":"Parcel analysis (_entity=parcel_analysis)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/rank-sites":{"post":{"operationId":"rankSites","summary":"Deterministic multi-site ranking/optimization under constraints (Phase 3)","description":"Rank candidate sites under hard constraints + signed weighted objectives (+maximize/-minimize). Three scoring modes: relative (min-max within batch, default), absolute (fixed 0-100, cross-run-stable), percentile (vs the viable-site population \u2014 'better than X% of viable sites', cross-run + cross-region comparable). Returns the DCHubEnvelope with _entity=ranked_sites: rank, objective_score, per-field normalized{}, normalization_basis.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidates","objectives"],"properties":{"candidates":{"type":"array","items":{"type":"object"},"description":"Pre-enriched candidate objects {id?, lat?, lng?, <metric fields>}; carry site_evaluation_handoff through"},"constraints":{"type":"object","description":"Hard filters {field: {min?, max?}}, fail-closed on a missing field"},"objectives":{"type":"object","description":"{field: signedWeight} \u2014 +weight maximizes, -weight minimizes"},"absolute":{"type":"boolean","description":"Fixed 0-100 scale (cross-run-stable)"},"percentile":{"type":"boolean","description":"Percentile vs the viable-site population (takes precedence over absolute)"},"top_k":{"type":"integer","default":3}}}}}},"responses":{"200":{"description":"Ranked sites (_entity=ranked_sites)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DCHubEnvelope"}}}}},"tags":["Public"]}},"/api/v1/facilities":{"get":{"operationId":"searchFacilities","summary":"Search data center facilities","description":"Search 24,800+ distinct facilities by location, provider, or market","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search term (city, provider, market)"},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 country code"},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100},"description":"Max results"}],"responses":{"200":{"description":"Facility search results"}},"tags":["Public"]}},"/api/v1/markets":{"get":{"operationId":"getMarkets","summary":"List all data center markets","description":"Returns all tracked markets with summary statistics","responses":{"200":{"description":"Market list"}},"tags":["Public"]}},"/api/v1/markets/compare":{"get":{"operationId":"compareMarkets","summary":"Compare data center markets","description":"Side-by-side comparison of two or more markets","parameters":[{"name":"markets","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated market slugs, e.g. phoenix,dallas. Required \u2014 the endpoint answers 400 without it."}],"responses":{"200":{"description":"Market comparison"}},"tags":["Public"]}},"/api/v1/dcpi/scores/{market_slug}":{"get":{"operationId":"getMarketDcpi","summary":"DC Hub Power Index (DCPI) for one market","description":"Per-market power-readiness: the BUILD/CAUTION/AVOID verdict is free; the numeric scores (composite_score, excess_power_score, constraint_score, time_to_power_months) come with the Developer plan and above and come back null otherwise. Recomputed daily. Use for 'is <market> good to build a data center?'.","parameters":[{"name":"market_slug","in":"path","required":true,"schema":{"type":"string"},"description":"Market slug, e.g. phoenix, northern-virginia, dallas"}],"responses":{"200":{"description":"Per-market DCPI scores + verdict"}},"tags":["Public"]}},"/api/v1/ai-capacity-index":{"get":{"operationId":"getAiCapacityIndex","summary":"AI Compute Capacity Index","description":"Markets ranked by AI-ready deployable MW for near-term (30/60/90-day) large-load siting, with hyperscale_ready flag and an honest ai_ready_mw proxy.","parameters":[{"name":"horizon","in":"query","schema":{"type":"integer","enum":[30,60,90],"default":90},"description":"Deployment horizon in days"}],"responses":{"200":{"description":"Ranked AI-ready markets"}},"tags":["Public"]}},"/api/news":{"get":{"operationId":"getNews","summary":"Latest industry news","description":"Aggregated from 40+ data center industry sources","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Max results"}],"responses":{"200":{"description":"News articles"}},"tags":["Public"]}},"/api/v1/transactions":{"get":{"operationId":"getTransactions","summary":"M&A transactions and deals","description":"Recent acquisitions, investments, and joint ventures","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"deal_type","in":"query","schema":{"type":"string","enum":["acquisition","investment","joint_venture","lease","development"]}}],"responses":{"200":{"description":"Transaction list"}},"tags":["Public"]}},"/api/v1/pipeline":{"get":{"operationId":"getPipeline","summary":"Construction pipeline","description":"Data centers under construction, announced or in planning, with operator, market and capacity where disclosed. Use for supply coming into a market rather than what is already operating. Requires an X-API-Key header for a key that opens it: a trial key or any paid plan, or any key holding pack credits (one credit per full answer). The free key from /api/v1/keys/claim does not open it.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Pipeline data"},"403":{"description":"No key, or a key that does not open it; the body lists the options that do"}},"tags":["Pro"]}},"/api/site-score":{"get":{"operationId":"getSiteScore","summary":"Site suitability score","description":"Composite 0-100 suitability score for data center development at one coordinate, with the component sub-scores behind it. A first-pass screen for a specific location, not a substitute for the per-layer power, fiber and risk calls. Requires an X-API-Key header for a key on the Pro plan or above. The free key from /api/v1/keys/claim does not open it: a key below Pro gets the preview, the verdict band and the counts with every score null.","parameters":[{"name":"lat","in":"query","schema":{"type":"number"},"required":true},{"name":"lon","in":"query","schema":{"type":"number"},"required":true},{"name":"state","in":"query","schema":{"type":"string"},"description":"US state abbreviation"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Site score"},"402":{"description":"No key, and the keyless allowance is used up"},"403":{"description":"A key that does not open it; the body names the plan that does"}},"tags":["Pro"]}},"/api/grid/fuel-mix":{"get":{"operationId":"getGridFuelMix","summary":"Real-time power grid fuel mix","description":"What a US grid is generating from RIGHT NOW \u2014 MW and share by fuel (gas, nuclear, coal, wind, solar, hydro, storage) with the reading's own timestamp. Use this instead of quoting an annual average when the question is about current conditions. Covers the seven US ISOs/RTOs only \u2014 not utility-level or non-US grids. Requires an X-API-Key header for a key on the Developer plan or above, or any key holding pack credits (one credit per full answer). The free key from /api/v1/keys/claim does not open it.","parameters":[{"name":"iso","in":"query","schema":{"type":"string","enum":["ERCOT","PJM","CAISO","MISO","SPP","NYISO","ISONE"]}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Grid fuel mix data"},"403":{"description":"No key, or a key that does not open it; the body lists the options that do"}},"tags":["Pro"]}},"/api/energy/prices/{state}":{"get":{"operationId":"getEnergyPrices","summary":"Electricity pricing by US state","description":"Industrial, commercial and residential electricity pricing for one US state from the latest EIA release, with the period it covers. Use for a first-pass cost comparison between states. These are state-level averages \u2014 not a utility tariff and not a negotiated large-load rate. Requires an X-API-Key header for a key on the Developer plan or above, or any key holding pack credits (one credit per full answer). The free key from /api/v1/keys/claim does not open it.","parameters":[{"name":"state","in":"path","schema":{"type":"string"},"required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Energy pricing"},"403":{"description":"No key, or a key that does not open it; the body lists the options that do"}},"tags":["Pro"]}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"X-API-Key header. Get one free in a single POST to https://dchub.cloud/api/v1/keys/claim \u2014 no email, no browser, no account. Paid plans at https://dchub.cloud/pricing raise the daily limits."}},"schemas":{"DCHubEnvelope":{"type":"object","description":"Universal response envelope for every DC Hub tool and endpoint. The STABLE anchor an agent branches on before parsing the entity payload: full-data, gated-preview and error responses all share it. `_entity` is the type discriminator; the entity-specific payload is passthrough (additionalProperties). Branch on `_entity` + `ok`.","required":["_entity"],"additionalProperties":true,"properties":{"_entity":{"type":"string","description":"Payload type discriminator \u2014 branch on this before parsing.","enum":["facility","market","grid","fiber","gas","deal","site","news","energy","incentives","risk","index","pipeline","infrastructure","export","changes","alert","meta","semantic_search","error","record"]},"ok":{"type":"boolean","description":"Success flag; false + _entity='error' on failure."},"_source":{"type":"string","example":"DC Hub \u2014 dchub.cloud"},"_cite":{"type":"string","description":"Attribution string (CC-BY-4.0)."},"citation":{"type":"object","properties":{"source":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"cite_as":{"type":"string"}}},"next_session":{"type":"object","description":"Context-aware next-step hints \u2014 the agent's state-machine menu for what to call next."}}}}},"tags":[{"name":"Public","description":"No key required \u2014 these answer cold"},{"name":"Pro","description":"Needs an X-API-Key. A free dev key is one POST to /api/v1/keys/claim \u2014 no email, no account; paid plans raise the limits."}]}