Tabby Disputes API — API Evangelist enrichment overlay

overlay: 1.0.0
info:
  title: Tabby Disputes API — API Evangelist enrichment overlay
  version: 1.0.0
  x-generated: '2026-08-26'
  x-method: generated
  x-source: openapi/tabby-disputes-api-openapi.yml
  x-note: >-
    Captures runtime semantics Tabby publishes in its documentation but does not express in the
    contract — rate limits, idempotency, reversal windows, environment selection and webhook
    delivery guarantees. Applies to openapi/tabby-disputes-api-openapi.yml; the original spec is never mutated.
extends: openapi/tabby-disputes-api-openapi.yml
actions:
  - target: $.info
    description: Record the region-specific base URLs and the API Evangelist enrichment provenance.
    update:
      x-api-evangelist:
        enriched: '2026-08-26'
        repo: https://github.com/api-evangelist/tabby
        conventions: conventions/tabby-conventions.yml
        errors: errors/tabby-problem-types.yml
        rate_limits: rate-limits/tabby-rate-limits.yml
        sandbox: sandbox/tabby-sandbox.yml
        data_model: data-model/tabby-data-model.yml
      x-regions:
        - region: UAE, Kuwait
          api: https://api.tabby.ai
          checkout: https://checkout.tabby.ai
          dashboard: https://merchant.tabby.ai
        - region: KSA
          api: https://api.tabby.sa
          checkout: https://checkout.tabby.sa
          dashboard: https://merchant.tabby.sa
  - target: $
    description: >-
      Record the rate limits Tabby publishes in prose but does not express in the contract, and the
      429 response the spec never declares.
    update:
      x-rate-limits:
        source: https://docs.tabby.ai/introduction/technical-requirements#rate-limit
        scope: per-api-key, per-operation-class
        exhaustion_status: 429
        response_headers: none
        live:
          create_session: 200 per 10s
          other: 100 per 1s
        test:
          create_session: 10 per 10s
          other: 50 per 1s
  - target: $.components.securitySchemes.bearerAuth
    description: Clarify the key prefixes that select environment, which the description omits.
    update:
      x-key-prefixes:
        live_secret: sk_
        test_secret: sk_test_
        live_public: pk_
        test_public: pk_test_
      x-environment-selection: >-
        Environment is chosen by the key, not by the host. The same base URL serves test and live.
  - target: $.paths['/api/v1/disputes'].get
    description: Record the hard listing cap and the live-only constraint.
    update:
      x-listing-cap: 100
      x-pagination: none
      x-environment: live only — disputes have no test mode and require live credentials.
  - target: $.paths['/api/v1/disputes/approve'].post
    description: Record the batch cap and irreversibility.
    update:
      x-batch-max: 20
      x-irreversible: true
      x-irreversible-note: Approving a dispute refunds the customer; no reversal is documented.
      x-agentic-consequence: moves-money
  - target: $.paths['/api/v1/disputes/challenge'].post
    description: Record the batch cap and the state precondition.
    update:
      x-batch-max: 20
      x-preconditions: Only disputes with status "new" can be challenged.
      x-agentic-consequence: contests-a-financial-record
  - target: $.paths['/api/v1/disputes/attachments/upload'].post
    description: Record the attachment constraints stated in the docs.
    update:
      x-max-file-size-bytes: 5242880
      x-allowed-content-types:
        - image/png
        - image/jpeg
        - application/pdf