API Evangelist enhancements for Treez Collection Service

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Treez Collection Service
  version: 1.0.0
extends: openapi/treez-collections-openapi.json
x-generated: '2026-08-30'
x-method: generated
x-source: Generated by API Evangelist from the verbatim Treez definition harvested at https://code.treez.io/openapi/collections.json.
  It records OUR annotations only - it never mutates the harvested contract. Every value below is drawn
  from a Treez-published page (the authentication reference, the API overview, the partner pages) or from
  the harvested document itself; nothing is invented.
actions:
- target: $.info
  description: Name the API and its owner. The harvested document carries a bare lowercase title and no
    contact, so an agent reading the contract alone cannot tell whose API it is.
  update:
    title: Treez Collection Service
    description: Organization-level product collections used to group products for merchandising.
    contact:
      name: Treez API Support
      email: api-support@treez.io
      url: https://code.treez.io/
    termsOfService: https://code.treez.io/page/legal
    x-provider: Treez
    x-provider-url: https://www.treez.io/
    x-api-catalog: https://code.treez.io/.well-known/api-catalog
- target: $.components.securitySchemes
  description: Document the authentication scheme the harvested contract omits entirely. Treez publishes
    it in prose at https://code.treez.io/reference/authentication; every one of the seven definitions
    declares an empty securitySchemes, so an agent cannot authenticate from the contract.
  update:
    TreezSelfSignedJWT:
      type: apiKey
      in: header
      name: Authorization
      description: 'Self-signed RSA JWT (RFC 7519), signed with the integrator private key whose public
        key Treez holds against a Certificate ID. Value is base64url(claims) + "." + base64(RSA-SHA256
        signature) - a TWO-part token that omits the JOSE header segment, so standard JWT libraries cannot
        produce it unmodified. Claims: aud (exact endpoint URL), iss (Certificate ID), oid (Organization
        ID), iat and exp in MILLISECONDS, jti recommended. Treez enforces exp = iat + 30000 ms; a TTL
        outside that returns 400. See authentication/treez-authentication.yml.'
      x-standard: RFC 7519 (with deviations)
      x-docs: https://code.treez.io/reference/authentication
- target: $
  description: 'Attach the runtime semantics an integrator needs but the contract does not state: no idempotency,
    no rate-limit signalling, no request-id header, and the reversibility posture of the write surface.'
  update:
    x-conventions: conventions/treez-conventions.yml
    x-error-catalog: errors/treez-problem-types.yml
    x-data-model: data-model/treez-data-model.yml
    x-lifecycle: lifecycle/treez-lifecycle.yml
    x-idempotency:
      supported: false
      note: No Idempotency-Key header is published for any operation.
    x-rate-limits:
      published: false
      note: No limits, no 429 response and no RateLimit headers are published.
    x-request-id:
      supported: false
      note: No correlation or request-id header is published.
- target: $.servers[0]
  description: Label the harvested server so an agent can tell production from the legacy surface without
    reading the docs.
  update:
    description: Treez production host. Dispensary APIs are addressed as /dispensary/{version}/{dispensary_name};
      Service APIs as /service/{service_name}/{version}. The {dispensary_name} slug is the subdomain of
      the customer own <tenant>.treez.io URL.