overlay: 1.0.0
info:
  title: API Evangelist enhancements — Carrier LYNX 2-way command Developer APIs
  version: 1.0.0
extends: carrier-global-lynx-2way-command-api-openapi.yaml
x-generated: '2026-09-05'
x-method: generated
x-source: openapi/carrier-global-lynx-2way-command-api-openapi.yaml
x-note: This overlay records API Evangelist annotations only. It never contradicts the published contract
  and it is never applied to the file in openapi/, which stays verbatim as Carrier serves it.
actions:
- target: $.info
  description: Add the machine-readable contact and licence metadata Carrier states in prose inside info.description
    but does not express as structured fields.
  update:
    contact:
      name: Carrier Lynx Fleet Support
      email: lynxfleetadmin@carrier.com
      url: https://doc-api.fleet.lynx.carrier.io/
    termsOfService: https://www.carrier.com/lynx/terms-of-use
- target: $
  description: Point at the Lynx Dev Portal as external documentation. The contract itself carries only
    a relative link (/api-documentation) inside info.description, which does not resolve for a consumer
    holding the file on disk.
  update:
    externalDocs:
      description: Lynx Fleet Dev Portal
      url: https://doc-api.fleet.lynx.carrier.io/api-documentation
- target: $.paths['/v1/check-command-status'].get
  description: Supply the operation summary and/or tag the published contract omits; summary is the operation's
    own description, restated, not new information.
  update:
    summary: This operation will return commands status list
- target: $.paths['/v1/get-commands'].get
  description: Supply the operation summary and/or tag the published contract omits; summary is the operation's
    own description, restated, not new information.
  update:
    summary: This operation will return list of available commands
- target: $.paths['/v1/send-commands'].post
  description: Supply the operation summary and/or tag the published contract omits; summary is the operation's
    own description, restated, not new information.
  update:
    summary: This operation will send 2-way commands
- target: $.paths['/v1/send-commands'].post
  description: Flag the consequence class of this operation for agent consumers. Carrier documents no
    idempotency key, no dry-run and no reversal for a call that actuates physical refrigeration equipment;
    recording that on the operation is an API Evangelist annotation, not a Carrier statement.
  update:
    x-consequence: physical-actuation
    x-idempotent: false
    x-reversible: false
    x-escalation: human-confirmation-recommended
    x-precondition: Commands should be executed only if the TRU (cooling unit) is powered on.
- target: $
  description: Record the published rate limit on the document. Carrier publishes 500,000 calls per month
    in the integration guide only; it appears nowhere in the contract, and there are no rate-limit response
    headers.
  update:
    x-rate-limit:
      quota: 500000
      unit: calls
      window: month
      scope: per-key
      exhaustion_status: 429
      response_headers: []
      source: https://doc-api.fleet.lynx.carrier.io/api-documentation