API Evangelist enrichment overlay for the VergeSense API

overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay for the VergeSense API
  version: 1.0.0
extends: ../openapi/vergesense-api-openapi.json
x-provenance:
  generated: '2026-09-02'
  method: generated
  source: >-
    Derived from the provider's own published documentation
    (https://vergesense.readme.io/reference/reference-getting-started,
    /reference/events, /reference/links) and from live probes of api.vergesense.com and
    mcp.vergesense.com. This overlay adds ONLY facts VergeSense itself publishes that are missing
    from the machine-readable contract. It never mutates openapi/vergesense-api-openapi.json.
  scope: >-
    The upstream spec is a ReadMe-generated 3.1.0 document with no tags, no components.schemas, no
    contact/license/termsOfService, only the AWS server, and no description on info. Every action
    below closes one of those gaps from a published source.
actions:
- target: $.info
  description: >-
    Add a description, contact, terms and license metadata block. VergeSense publishes all of this on
    its site and support pages but none of it reaches the generated spec.
  update:
    description: >-
      REST and webhook API for the VergeSense Cloud occupancy intelligence platform. Read buildings,
      floors, spaces, space types, neighborhoods and space groups; pull hourly and aggregate
      occupancy metrics; inventory sensors and gateways; call the Large Spatial Model Predict API;
      and manage webhook subscriptions for space_report, space_availability and motion_detected
      events. Authenticated with a vs-api-key header. Collection endpoints follow JSON:API
      pagination. Date-versioned via the vs-version header.
    contact:
      name: VergeSense Support
      email: support@vergesense.com
      url: https://support.vergesense.com/hc/en-us
    termsOfService: https://www.vergesense.com/legal
- target: $.servers
  description: >-
    The upstream spec declares only the AWS host. The Getting Started page documents an Azure
    deployment as an equal alternative for Azure-hosted tenants, so a client generated from the spec
    alone cannot reach half the customer base.
  update:
  - url: https://api.vergesense.com
    description: AWS (default)
  - url: https://api.azure.vergesense.com
    description: Azure deployment
- target: $.paths[*][*]
  description: >-
    Document the global 403 that every operation can return. The upstream spec declares 400 (and 404
    on five metrics operations) but never declares the authentication failure, even though the docs
    state plainly that a missing header or invalid token returns 403.
  update:
    responses:
      '403':
        description: >-
          Forbidden. Caused by a missing vs-api-key HTTP header or an invalid API token. Also
          returned when the key is not scoped to the requested building.
      '429':
        description: >-
          Too Many Requests. A rate limit of 120 requests/minute per source IP is enforced across
          most endpoints. No Retry-After or RateLimit-* header is returned.
- target: $.paths['/spaces/detections'].get
  description: Record the published response cap and the JSON:API pagination profile as machine-readable extensions.
  update:
    x-pagination:
      style: jsonapi
      params: ['page[number]', 'page[size]']
      links: [next, previous]
      max_records: 10000
- target: $.paths['/hardware/sensors'].get
  description: Record the published 1,000-record response cap.
  update:
    x-pagination:
      style: jsonapi
      params: ['page[number]', 'page[size]']
      links: [next, previous]
      max_records: 1000
- target: $.paths['/hardware/gateways'].get
  description: Record the published 1,000-record response cap.
  update:
    x-pagination:
      style: jsonapi
      params: ['page[number]', 'page[size]']
      links: [next, previous]
      max_records: 1000
- target: $.paths['/spaces/types'].get
  description: >-
    Flag the deprecation VergeSense announced on 2026-03-04 with an effective date of 2026-04-01.
    Several space-type attributes are being removed and the upstream spec carries no deprecation
    signal at all.
  update:
    x-deprecation:
      partial: true
      scope: various space type attributes, not the operation itself
      effective: '2026-04-01'
      announced: '2026-03-04'
      announcement: https://headwayapp.co/vergesense-changelog/deprecating-space-type-attributes-333231
- target: $.paths['/webhooks/{id}']
  description: >-
    Record the reversibility posture of the webhook write surface — the only writes on this API.
    DELETE is the single irreversible operation; disable/enable is the symmetric alternative.
  update:
    x-reversibility:
      delete:
        reversible: false
        preferred_alternative: POST /webhooks/{id}/disable
        note: >-
          A deleted webhook cannot be restored and a recreated one receives a new id. Disable
          preserves configuration and id and is fully reversible with enable.
      patch:
        reversible: true
        requires: the caller must read GET /webhooks first — no revision history or restore exists
- target: $.components.securitySchemes.sec0
  description: >-
    Add the human-readable description the generated scheme lacks, including how a key is obtained
    and what it is scoped to.
  update:
    description: >-
      API key sent in the vs-api-key header on every request. Keys are requested by emailing
      support@vergesense.com for a VergeSense Developer account, then generated under
      Settings > API Keys in the VergeSense Cloud app. A key is scoped to a selected set of buildings
      and can be rotated in-app. There are no OAuth scopes and no read-only key type. All requests
      must use https.
- target: $
  description: >-
    Record the sibling agent surface. VergeSense runs an OAuth-protected remote MCP server that is
    undocumented in its own reference and invisible from this contract.
  update:
    x-mcp:
      endpoint: https://mcp.vergesense.com/mcp
      transport: streamable-http
      auth: oauth2
      protected_resource_metadata: https://mcp.vergesense.com/.well-known/oauth-protected-resource/mcp
      authorization_server: https://vergesense.auth0.com/
      verified: probed
      probed: '2026-09-02'
    x-webhooks-catalog: ../asyncapi/vergesense-webhooks.yml