API Evangelist enhancements for Fixflo API v2

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for Fixflo API v2
  version: 1.0.0
extends: openapi/fixflo-api-v2-openapi.yml
x-generated: '2026-07-26'
x-method: generated
x-source: >-
  API Evangelist enrichment round 2026-07-26. Captures our enhancements to the
  harvested Fixflo v2 OpenAPI without mutating it: the real production base-URL
  pattern, the documented but unspecified access gate, rate limiting, error
  envelope, pagination and webhook facts, and the operations that carry
  natural-key upsert semantics. Every value is sourced from the Fixflo developer
  portal or the spec itself.
actions:
- target: $.info
  update:
    x-apievangelist-slug: fixflo
    x-apievangelist-enriched: '2026-07-26'
    x-access-gate: >-
      Every use of the Fixflo API is subject to the signed Application Developer
      and API Licence Agreement. Keys are not self-serve: contact
      support@fixflo.com, describe the use case, register the integration, sign
      the agreement.
    x-licence-agreement: https://fixflostore.blob.core.windows.net/live-assets/SystemApplicationDeveloperAndAPILicenseAgreement.pdf
    x-rate-limit:
      documented: true
      limit: not below 500 requests per minute
      status_code: 429
      retry_after_header: false
      source: https://api-docs.fixflo.com/72b66de24898e-welcome-to-fixflo
    x-error-envelope:
      schema: Envelope
      fields: [HttpStatusCode, HttpStatusCodeDesc, Errors, Messages]
      rfc9457: false
    x-pagination:
      style: page-number
      parameters: [Pg, Page]
      envelope: PrevNextPager
      follow_links: [NextURL, PreviousURL]
    x-idempotency:
      idempotency_key_header: none
      mechanism: natural-key upsert on external references
      detail: conventions/fixflo-conventions.yml
- target: $.servers
  update:
  - url: https://{subdomain}.fixflo.com/api/v2
    description: >-
      Production. Each Fixflo agency account is served from its own subdomain;
      the harvested spec lists only the shared sandbox and a Fixflo-internal dev
      host, so the real production pattern is added here.
    variables:
      subdomain:
        default: your-subdomain
        description: The customer's Fixflo subdomain.
  - url: https://api-sandbox.fixflo.com/api/v2
    description: live sandbox (provisioned on request; not self-serve)
  - url: https://plus.dev.fixflo.com/api/v2
    description: dev (Fixflo internal)
- target: $.components.securitySchemes.Bearer
  update:
    description: >-
      A 64-character alphanumeric token generated by a user from inside their own
      live Fixflo system and sent as "Authorization: Bearer [token]". It is
      separate from the user's password and may be stored by a third party. There
      are no scopes; the token carries the privileges of the user who created it.
      HTTPS is mandatory — a non-TLS request errors with 401.
    x-token-format: 64-character alphanumeric string
    x-self-serve: false
    x-docs: https://api-docs.fixflo.com/72b66de24898e-welcome-to-fixflo
- target: $.paths['/Agent'].post
  update:
    x-idempotency:
      mechanism: natural-key upsert
      natural_key: ExternalAgentRef
      note: >-
        Create or update. A retried call carrying the same ExternalAgentRef
        converges on one agent record rather than creating a duplicate.
- target: $.paths['/Property'].post
  update:
    x-idempotency:
      mechanism: natural-key upsert
      natural_key: ExternalPropertyRef
      note: >-
        Create or update. PropertyId > 0 updates the existing property;
        ExternalPropertyRef must be unique per agency.
- target: $.paths['/Estate'].post
  update:
    x-idempotency:
      mechanism: natural-key upsert
      natural_key: ExternalEstateRef
- target: $.paths['/Issue/{Id}/ExternalRef'].post
  update:
    x-idempotency:
      mechanism: natural-key upsert
      natural_key: ExternalRef
      note: External Ref must be unique per agency; overwrites the current value if one exists.
- target: $.paths['/Webhook/Subscribe'].post
  update:
    x-event-surface:
      events:
      - Issue state change
      signing:
        header: ff-signature
        algorithm: HMAC SHA256
        value_format: sha256={hash}
      retries:
        max_attempts: 6
        window: approximately 10 minutes
      source_host: webhook.fixflo.com
      detail: asyncapi/fixflo-webhooks.yml
      docs: https://api-docs.fixflo.com/5cc9374300b99-webhooks