API Evangelist enhancements — Paedae Beacons API

# generated: 2026-08-13
# method: generated
# source: https://docs.gimbal.com/rest.html + this repo's derived artifacts
overlay: 1.0.0
info:
  title: API Evangelist enhancements — Paedae Beacons API
  version: 1.0.0
extends: paedae-beacons-api-openapi.yml
x-generated: '2026-08-13'
x-method: generated
x-source: https://docs.gimbal.com/rest.html + repo artifacts
actions:
- target: $.info
  description: 'Record the real, dated provenance of this document: it was generated by API Evangelist from the published Gimbal REST reference, not published by the provider.'
  update:
    x-provenance:
      method: generated
      source: https://docs.gimbal.com/rest.html
      generated-by: API Evangelist enrichment pipeline
      note: Gimbal/Paedae publishes no machine-readable API definition. This document captures the surface documented in the HTML reference.
- target: $.info
  description: 'State the operator chain a consumer needs to resolve support and legal: Paedae built Gimbal, Infillion operates it, and both paedae.com and gimbal.com now redirect to infillion.com.'
  update:
    x-operator:
      company: Paedae
      product: Gimbal
      operated-by: Infillion
      developer-portal: https://docs.gimbal.com
      management-console: https://manager.gimbal.com
      support: https://support.gimbal.com/hc/en-us/
      status: http://status.gimbal.com
- target: $.info
  description: 'Attach the runtime semantics the HTML reference states in prose but the definition cannot express: no rate limits, no idempotency, no deprecation policy, and a numeric error-code envelope.'
  update:
    x-runtime-semantics:
      rate-limits:
        documented: false
        artifact: rate-limits/paedae-rate-limits.yml
      idempotency:
        supported: false
        artifact: conventions/paedae-conventions.yml
      deprecation-policy:
        published: false
        artifact: lifecycle/paedae-lifecycle.yml
      error-envelope:
        style: numeric-code
        artifact: errors/paedae-problem-types.yml
      webhooks:
        artifact: asyncapi/paedae-webhooks.yml
- target: $.components.securitySchemes.OrganizationServerApiKey
  description: Spell out the exact header value format documented in the reference, which a bare apiKey scheme cannot convey.
  update:
    x-value-format: Token token=<organization_server_api_key>
    x-issued-in: Gimbal Manager > Organizations
    x-docs: https://docs.gimbal.com/rest.html
- target: $.paths['/beacons'].get.responses['200']
  description: Document the pagination counter headers the reference says are returned on paginated collection responses.
  update:
    headers:
      Total-Beacons:
        description: Total number of records matching the filters. Zero when none are found.
        schema:
          type: integer
      Total-Pages:
        description: Total number of pages (total records / per_page). Not sent when no records are found.
        schema:
          type: integer
      Current-Page:
        description: The current page, matching the page query parameter. Not sent when no records are found.
        schema:
          type: integer