API Evangelist enhancements — OwnLocal API — Reports Data API

overlay: 1.0.0
info:
  title: API Evangelist enhancements — OwnLocal API — Reports Data API
  version: 1.0.0
extends: ../openapi/ownlocal-reports-data-api-openapi.yml
x-generated: '2026-08-12'
x-method: generated
x-source: openapi/_original/ownlocal-swagger.json (verbatim from https://admin.austin.ownlocal.com/api-docs/v1/swagger.json)
  cross-read against https://api.docs.ownlocal.com/
x-note: 'Records what API Evangelist added on top of OwnLocal''s own contract during the Swagger 2.0 -> OpenAPI
  3.1.0 conversion. Nothing here changes OwnLocal''s described behaviour: every added value is either a restatement
  of something OwnLocal publishes in prose (the server host, the auth mechanics, support contact) or a structural
  identifier the source omitted (operationIds, tag declarations). No endpoint, parameter, field or schema is invented.
  The original is preserved byte-for-byte at openapi/_original/ownlocal-swagger.json and is never mutated.'
actions:
- target: $
  description: Add servers[]. OwnLocal's published Swagger 2.0 declares no host, basePath or schemes, so the source
    contract never names the server it describes. The host is taken verbatim from the published API reference
    at https://api.docs.ownlocal.com/, where every curl example calls https://admin.austin.ownlocal.com/api/v1/...
  update:
    servers:
    - url: https://admin.austin.ownlocal.com
      description: OwnLocal production API host (per the published API reference)
- target: $
  description: Link the machine contract back to the human reference it was cross-read against.
  update:
    externalDocs:
      description: OwnLocal API Docs
      url: https://api.docs.ownlocal.com/
- target: $.info
  description: Add contact (support@ownlocal.com / the support page, both published by OwnLocal) and a tag-scoped
    description. The source info block carries only title and version.
  update:
    description: Performance reporting for ads and businesses — impressions, interaction breakdowns, leads, digital
      lift and search-rank history.
    contact:
      name: OwnLocal Support
      email: support@ownlocal.com
      url: https://www.ownlocal.com/support/
- target: $
  description: Declare the tag. The source Swagger uses tags on operations but never declares them at the root,
    so no tag carries a description.
  update:
    tags:
    - name: Reports Data API
      description: Performance reporting for ads and businesses — impressions, interaction breakdowns, leads,
        digital lift and search-rank history.
- target: $.paths['/api/v1/reports/ads'].get
  description: Add operationId 'getAdsReport'. None of OwnLocal's 13 operations declares an operationId, which
    blocks code generation and leaves agent tooling with no stable handle. Assigned deterministically from the
    HTTP method and resource path.
  update:
    operationId: getAdsReport
- target: $.paths['/api/v1/reports/business'].get
  description: Add operationId 'getBusinessReport'. None of OwnLocal's 13 operations declares an operationId,
    which blocks code generation and leaves agent tooling with no stable handle. Assigned deterministically from
    the HTTP method and resource path.
  update:
    operationId: getBusinessReport
- target: $.components.securitySchemes.apiKey
  description: 'Describe the apiKey scheme. The source declares type/name/in with no description, which omits
    the single most error-prone fact about this API: the key is sent RAW in the Authorization header with no Bearer
    prefix, and is issued manually by OwnLocal support. Stated in the published reference.'
  update:
    description: Organization API key sent raw (no scheme prefix) in the Authorization header. Keys are issued
      by OwnLocal support; there is no self-serve key provisioning.
- target: $.components.schemas.ads_report
  description: Resolve a dangling $ref. The source Swagger's 'ads_report.ads' references '#/definitions/ad_reach',
    which the document never defines, leaving the spec unresolvable. The missing schema is NOT invented here —
    the $ref is replaced with an unconstrained object carrying x-ownlocal-unresolved-ref, so the contract resolves
    while the provider's defect stays visible and attributable.
  update: {}
  x-ownlocal-unresolved-ref: '#/definitions/ad_reach'
- target: $.components.schemas.business_report
  description: Resolve a dangling $ref. The source Swagger's 'business_report.reach_report' references '#/definitions/business_reach',
    which the document never defines, leaving the spec unresolvable. The missing schema is NOT invented here —
    the $ref is replaced with an unconstrained object carrying x-ownlocal-unresolved-ref, so the contract resolves
    while the provider's defect stays visible and attributable.
  update: {}
  x-ownlocal-unresolved-ref: '#/definitions/business_reach'