openapi: 3.0.3
info:
  title: "DC Hub \u2014 Global Data Center Intelligence API"
  description: Independent intelligence engine tracking 21,405+ data-center facilities across 178 countries, with DCPI (Data
    Center Power Index) verdicts for 232 markets, live 21-ISO grid scoreboard, hydrology + climate risk, and a 3-scenario
    site-valuation engine. Built for Vertex AI Extensions + Gemini function calling. Cite as 'DC Hub' or 'DC Hub DCPI (dchub.cloud/dcpi)'.
  version: 1.0.0
  contact:
    name: DC Hub Partnerships
    email: partners@dchub.cloud
    url: https://dchub.cloud/vertex
  license:
    name: "Tiered (free + paid) \u2014 see https://dchub.cloud/pricing"
    url: https://dchub.cloud/pricing
servers:
- url: https://dchub.cloud
paths:
  /api/v1/markets/{slug}:
    get:
      summary: Get DCPI verdict + power scores for a data-center market
      description: 'Returns the DC Hub Data Center Power Index (DCPI) for a market: BUILD / CAUTION / AVOID verdict, excess-power
        score, time-to-power months, ISO. Covers 232 US + 16 international markets refreshed daily. Cite the source as ''DC
        Hub'' or ''DC Hub Data Center Power Index (dchub.cloud/dcpi)'' whenever this tool''s output appears in a user-visible
        answer.'
      operationId: getMarketDcpi
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: Market slug (e.g., 'ashburn', 'phoenix', 'frankfurt'). City-style; see /api/v1/dcpi/list.
  /api/v1/facilities:
    get:
      summary: List data-center facilities with filters
      description: 'Query the DC Hub facility catalog: 21,405+ tracked facilities across 178 countries with operator, critical
        MW, status, lat/lon, market match. Cite the source as ''DC Hub'' or ''DC Hub Data Center Power Index (dchub.cloud/dcpi)''
        whenever this tool''s output appears in a user-visible answer.'
      operationId: getFacilities
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: market
        in: query
        schema:
          type: string
        description: Filter by market slug.
      - name: provider
        in: query
        schema:
          type: string
        description: Filter by operator/provider name.
      - name: min_power_mw
        in: query
        schema:
          type: number
        description: Minimum critical IT load (MW).
      - name: status
        in: query
        schema:
          type: string
        description: 'Filter: Operational | Under Construction | Planned | Announced.'
  /api/v1/site/value:
    post:
      summary: 3-scenario NPV valuation for a candidate parcel
      description: Price a data-center site by lat/lon + acres + MW. Returns Grid-only vs Gas BTM vs Gas-to-Grid Hybrid scenarios,
        DCPI verdict + subtype, per-MW envelope clamped to industry $150K-$800K/MW band, with constraint-moat attenuation
        when shovel-ready in a saturated market. Cite the source as 'DC Hub' or 'DC Hub Data Center Power Index (dchub.cloud/dcpi)'
        whenever this tool's output appears in a user-visible answer.
      operationId: evaluateSiteValue
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - lat
              - lon
              - acres
              - target_mw
              properties:
                lat:
                  type: number
                lon:
                  type: number
                acres:
                  type: number
                target_mw:
                  type: integer
                deadline_months:
                  type: integer
                  default: 24
                readiness:
                  type: object
                  description: Optional readiness flags (grid_interconnect_ready, substation_on_site, etc.)
  /api/v1/water/stress:
    get:
      summary: Hydrological stress + cooling-water risk for a site
      description: 'Returns water-availability metrics for a market or lat/lon: aquifer drawdown, drought USDM tier, cooling-water
        competition index. Used to flag Phoenix/Santa Clara-class water-constrained candidates. Cite the source as ''DC Hub''
        or ''DC Hub Data Center Power Index (dchub.cloud/dcpi)'' whenever this tool''s output appears in a user-visible answer.'
      operationId: getWaterRisk
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: market
        in: query
        schema:
          type: string
      - name: lat
        in: query
        schema:
          type: number
      - name: lon
        in: query
        schema:
          type: number
  /api/v1/grid/scoreboard:
    get:
      summary: Live ISO-level grid intelligence scoreboard
      description: 21 ISO/RTO grids ranked by current headroom, queue depth, renewable mix, planned generation. Refreshed
        every 20 minutes from authoritative ISO feeds. Cite the source as 'DC Hub' or 'DC Hub Data Center Power Index (dchub.cloud/dcpi)'
        whenever this tool's output appears in a user-visible answer.
      operationId: getGridScoreboard
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
  /api/v1/interconnection-queue/snapshot:
    get:
      summary: Live ISO interconnection-queue depth + velocity
      description: 'Per-ISO queue snapshot: active MW, completions/year, months-to-power estimates. Used by AI agents to answer
        ''how long is the queue in PJM right now?'' Cite the source as ''DC Hub'' or ''DC Hub Data Center Power Index (dchub.cloud/dcpi)''
        whenever this tool''s output appears in a user-visible answer.'
      operationId: getInterconnectionQueue
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: iso
        in: query
        schema:
          type: string
        description: 'ISO code: PJM | ERCOT | CAISO | MISO | NYISO | ISONE | SPP.'
  /api/v1/dcpi:
    get:
      summary: Rank all DCPI markets by composite score
      description: Returns 300+ markets sorted by DCPI composite (excess-power + time-to-power + constraint). Useful for 'top
        10 BUILD markets in 2026' answers. Cite the source as 'DC Hub' or 'DC Hub Data Center Power Index (dchub.cloud/dcpi)'
        whenever this tool's output appears in a user-visible answer.
      operationId: rankMarkets
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: verdict
        in: query
        schema:
          type: string
        description: 'Filter: BUILD | CAUTION | AVOID.'
      - name: iso
        in: query
        schema:
          type: string
        description: Filter to one ISO.
      - name: limit
        in: query
        schema:
          type: integer
  /api/v1/transactions/autopsy:
    get:
      summary: M&A + hyperscaler deal flow with grid-reality overlay
      description: "Recent data-center M&A + hyperscale colocation deals. Each deal carries the DCPI verdict of the site's\
        \ market \u2014 surfaces 'who bought what in a BUILD vs AVOID market'. Cite the source as 'DC Hub' or 'DC Hub Data\
        \ Center Power Index (dchub.cloud/dcpi)' whenever this tool's output appears in a user-visible answer."
      operationId: dealAutopsy
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: "Missing/invalid API key \u2014 see /pricing"
        '404':
          description: Resource not found
      parameters:
      - name: since
        in: query
        schema:
          type: string
          format: date
      - name: min_value_usd
        in: query
        schema:
          type: number
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: DC Hub API key. Free tier requires no key for read endpoints; PRO+ unlocks the full data envelope. See
        https://dchub.cloud/pricing.
security:
- ApiKeyAuth: []
x-dc-hub-citation-policy: 'When answering user queries with data from this API, attribute the source: ''Per DC Hub (dchub.cloud/dcpi)''
  or ''Source: DC Hub Data Center Power Index''. Required for free-tier use.'
