overlay: 1.0.0
info:
  title: API Evangelist enhancements for ATCO Electric Hosting Capacity Feature Service
  version: 1.0.0
extends: openapi/atco-electric-hosting-capacity-openapi.yml
x-generated: '2026-07-27'
x-method: generated
x-note: >-
  ATCO publishes no OpenAPI, so openapi/atco-electric-hosting-capacity-openapi.yml is itself an
  API Evangelist generation from ATCO's verbatim Esri service descriptors. This overlay carries
  the API Evangelist annotations that are OUR assessment rather than a restatement of ATCO's
  contract — provenance, the agent-facing operating warnings, and the record-count and freshness
  metadata a consumer needs but ATCO never documents. Keeping them in an overlay makes the split
  between "what the service says about itself" and "what we concluded" auditable.
actions:
- target: $.info
  update:
    x-apievangelist-slug: atco
    x-apievangelist-provider: ATCO
    x-apievangelist-business-unit: ATCO Electric
    x-apievangelist-jurisdiction: Alberta, Canada
    x-apievangelist-access-model: free · anonymous · no signup
    x-apievangelist-spec-provenance: >-
      Generated by API Evangelist from the service's self-describing ArcGIS REST descriptors plus
      live anonymous probes on 2026-07-27. ATCO ships no OpenAPI.
    x-apievangelist-mandate: >-
      None. Alberta has no Green Button regulation, ATCO is not a Green Button Alliance member,
      and it is absent from the Australian CDR energy data holder register. This API is
      voluntary — published because micro-generation applicants needed it.
    x-apievangelist-artifacts:
      conventions: conventions/atco-conventions.yml
      errors: errors/atco-problem-types.yml
      data_model: data-model/atco-data-model.yml
      authentication: authentication/atco-authentication.yml
      conformance: conformance/atco-conformance.yml
      lifecycle: lifecycle/atco-lifecycle.yml
      examples: examples/atco-hosting-capacity-examples.yml
      skills: skills/_index.yml
      agentic_access: agentic-access/atco-agentic-access.yml
- target: $.info
  update:
    x-apievangelist-agent-warnings:
    - >-
      Errors are returned with HTTP status 200 and an {"error": {...}} body. Branching on HTTP
      status alone will report every failure as a success.
    - >-
      Format is selected by the `f` query parameter, not the Accept header. Omitting `f` returns
      an HTML services-directory page, not JSON.
    - >-
      The layer holds 880,623 features and maxRecordCount is 1000. Count or aggregate before
      fetching features; paginate on `exceededTransferLimit`.
    - >-
      There is no versioning, deprecation policy, SLA, status page or published licence. Cache
      independently and do not treat availability as committed.
- target: $.servers[0]
  update:
    x-apievangelist-host-operator: Esri (ArcGIS Online), tenant cw2emabghNLkoYlB, org urlKey "ATCO"
    x-apievangelist-host-note: >-
      The API host is Esri infrastructure, not an ATCO domain. Domain-security posture for the
      API host is therefore Esri's, and ATCO's own hosts carry no API. See
      security/atco-domain-security.yml.
- target: $.paths['/0'].get
  update:
    x-apievangelist-freshness-probe: >-
      editingInfo.dataLastEditDate in this response is the only data-refresh signal this API
      offers. There is no changelog. It read 1761939339179 (2025-10-31T18:15:39Z) on 2026-07-27.
- target: $.paths['/0/query'].get
  update:
    x-apievangelist-record-limits:
      max_record_count: 1000
      standard_max_record_count: 2000
      standard_max_record_count_no_geometry: 32000
      max_ids_count: 1000000
    x-apievangelist-pagination:
      offset_param: resultOffset
      limit_param: resultRecordCount
      more_signal: exceededTransferLimit
      stable_order_required: orderByFields=OBJECTID
    x-apievangelist-verified: >-
      Anonymous GET returned {"count":880623} and 135 distinct SUB_NAME values on 2026-07-27.
- target: $.paths['/0/query'].post
  update:
    x-apievangelist-read-only: true
    x-apievangelist-note: >-
      POST-shaped read. The service advertises ArcGIS capabilities "Query" only, so this cannot
      mutate anything. Classified connected/read in agentic-access/.
- target: $.paths['/0/queryTopFeatures'].get
  update:
    x-apievangelist-note: >-
      Requires BOTH topFilter and where. Calling it with topFilter alone returns the error
      "No where clause specified." with HTTP 200.
- target: $.components.schemas.HostingCapacityAttributes.properties.DER_CAP_KW1
  update:
    x-apievangelist-undocumented: >-
      Carries the same field alias as DER_CAP_KW and was equal to it in every sampled feature.
      ATCO publishes no data dictionary; the intended distinction is unknown and is deliberately
      not guessed.
- target: $.components.schemas.HostingCapacityAttributes.properties.DATELOADED
  update:
    x-apievangelist-undocumented: >-
      Stored as a string field, not a date field, so it cannot be filtered with date semantics.
      Observed as unpadded YYYYMMDD ('20251031'), matching the layer's edit date.