API Evangelist enhancements for the Hiver API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Hiver API
  version: 1.0.0
extends: ../openapi/hiver-api-openapi.json
x-provenance:
  generated: '2026-08-22'
  method: generated
  source: >-
    Generated from Hiver's own published documentation at https://developer.hiverhq.com/hiver-api
    and applied over the verbatim contract at openapi/hiver-api-openapi.json. The original spec
    is never mutated. Every value below is quoted or paraphrased from Hiver's own prose - nothing
    is invented.
  note: >-
    The scorer parses the ORIGINAL spec, so this overlay improves derived artifacts and any
    consumer who chooses to apply it; it does not change Hiver's own contract-content score.
actions:
  - target: $.info
    description: >-
      Add a real title, contact and description. The published spec carries only
      title "hiver-api" and version "1.0.0" - no description, no contact, no licence, no terms.
    update:
      title: Hiver API
      description: >-
        The Hiver REST API exposes Shared Inboxes and their conversations, users, tags and
        internal notes. Authenticate with an admin-generated API key sent as an HTTP Bearer
        token. All successful responses are wrapped in a top-level `data` object; list responses
        add `data.pagination.next_page`, an opaque forward cursor. Rate limits are 1 request per
        second per account and 5000 requests per day, signalled only by HTTP 429 with no
        rate-limit response headers. API access requires a Pro plan or above.
      contact:
        name: Hiver Support
        url: https://help.hiverhq.com/
      termsOfService: https://hiverhq.com/terms
      x-documentation: https://developer.hiverhq.com/hiver-api
  - target: $.components
    description: >-
      Declare the Bearer API key as a securityScheme. The published spec has NO
      components.securitySchemes; authentication is modelled as a required `Authorization`
      header parameter repeated on all 12 operations, which no generated client can discover
      as auth.
    update:
      securitySchemes:
        bearerApiKey:
          type: http
          scheme: bearer
          description: >-
            Hiver account API key, generated by an administrator under
            Admin Panel -> Integrations -> Developer APIs. Carries admin privileges.
  - target: $
    description: Apply the security scheme globally, as Hiver's docs describe it.
    update:
      security:
        - bearerApiKey: []
  - target: $.servers
    description: Label the single production server.
    update:
      - url: https://api2.hiverhq.com/v1
        description: Production
  - target: $.info
    description: >-
      Record the documented runtime semantics that have no home in OpenAPI 3.0 fields, so an
      agent reading only the contract can find them.
    update:
      x-rate-limits:
        per_second: 1
        per_day: 5000
        scope: per-account
        status_on_exhaustion: 429
        headers: none published
        guidance: retry with exponential backoff; continuous 429 retries may blacklist the IP or key
        source: https://developer.hiverhq.com/hiver-api
      x-pagination:
        style: opaque-cursor
        params: [limit, sort_by, sort_order, next_page]
        limit_min: 10
        limit_max: 100
        limit_default: 10
        response_field: data.pagination.next_page
        termination: next_page is null
      x-error-envelopes:
        - '{"errors":[{"message":"..."}]}'
        - '{"Message":"..."}'
      x-idempotency:
        supported: false
        note: No Idempotency-Key header is published; the three POST operations are not safe to blind-retry.
      x-reversibility:
        status: documented
        note: >-
          PATCH conversation is reversible only by re-applying previously read values; tag
          creation, shared drafts and notes have no published reversal endpoint and no window.