API Evangelist enhancements for ESGx Buildings API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for ESGx Buildings API
  version: 1.0.0
extends: openapi/measurabl-esgx-buildings-openapi.yml
x-generated: '2026-08-01'
x-method: generated
x-source: openapi/_original/measurabl-esgx-buildings-openapi.json
x-note: Enhancements API Evangelist derives on top of the harvested Measurabl spec. The original is never mutated.
  The two substantive gaps this overlay addresses are (1) the document declares NO servers array, so no client or
  generator can resolve a base URL from the spec alone, and (2) 39 of 39 operations carry no operationId, which
  blocks operation-level referencing from Arazzo, agent skills and SDK generators.
actions:
- target: $.info
  update:
    x-apievangelist-provider: measurabl
    x-apievangelist-artifacts:
      authentication: authentication/measurabl-authentication.yml
      conventions: conventions/measurabl-conventions.yml
      errors: errors/measurabl-problem-types.yml
      rate-limits: rate-limits/measurabl-rate-limits.yml
      data-model: data-model/measurabl-data-model.yml
      lifecycle: lifecycle/measurabl-lifecycle.yml
      conformance: conformance/measurabl-conformance.yml
    x-media-type: application/vnd.api+json
    x-standard: JSON:API 1.0
    x-idempotency: not-supported
- target: $
  description: The published document declares no servers array. This is the production base URL, confirmed by the
    path prefix and by the OAuth token URL declared in components.securitySchemes.
  update:
    servers:
    - url: https://api.measurabl.com/insights/v0
      description: Measurabl production (/insights/v0)
- target: $.components.securitySchemes.OAuth2
  description: Record how credentials are actually obtained; the spec declares the token URL but not the provisioning
    path or the fact that no scopes exist.
  update:
    x-provisioning: Client key and secret are issued per organization by a Measurabl Customer Delivery Manager;
      API access requires Premium Tier entitlement.
    x-scopes: none - the clientCredentials flow declares an empty scopes map, so authorization is entitlement-based
      rather than scope-based.
    x-docs: https://support.measurabl.com/hc/en-us/articles/15889532915085-How-do-I-authenticate-with-Measurabl-s-Core-API-
- target: $.tags
  description: Declare the 7 tags used by operations in this document; the original declares an empty/absent top-level
    tags array while tagging every operation.
  update:
  - name: Buildings
    x-operation-count: 3
  - name: Carbon Estimates
    x-operation-count: 8
  - name: Certification Lookups
    x-operation-count: 8
  - name: Energy Estimates
    x-operation-count: 8
  - name: Exports
    x-operation-count: 3
  - name: Ordinance Lookups
    x-operation-count: 8
  - name: Ordinances
    x-operation-count: 1
- target: $.components.schemas.failure
  update:
    x-error-catalog: errors/measurabl-problem-types.yml
    x-format: jsonapi-errors
    x-rfc9457: false
- target: $.paths
  description: '39 of 39 operations in this document have no operationId. API Evangelist does NOT synthesize them
    into the spec: an invented operationId would be indistinguishable from a published one downstream. This action
    records the gap so it can be raised with Measurabl. Agent skills in skills/ therefore reference operations by
    METHOD + path, which are verbatim real.'
  update:
    x-apievangelist-gap:
      missing_operation_ids: 39
      total_operations: 39
      severity: high
- target: $.paths
  description: 'Six CRREM paths are published as EMPTY path items - they declare no HTTP operations at all: /insights/v0/crrem_lookups,
    /insights/v0/crrem_lookups/{id}, /insights/v0/crrem_lookup_batches/{id}, /insights/v0/crrem_lookup_batches/{id}/crrem_lookups,
    /insights/v0/crrem_lookup_batches/upload, /insights/v0/crrem_lookup_batches/export. The CRREM transition-risk
    capability is therefore visible in the spec but not callable from it. Recorded, not repaired - API Evangelist
    does not invent operations.'
  update:
    x-apievangelist-gap:
      empty_path_items: 6
      capability: CRREM transition-risk lookups
      severity: high