API Evangelist enhancements for the AskNicely API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the AskNicely API
  version: 1.0.0
extends: openapi/asknicely-openapi.yml
x-generated: '2026-08-06'
x-method: generated
x-source: >-
  The AskNicely OpenAPI in this repo was itself assembled by API Evangelist from AskNicely's HTML API
  reference. This overlay records the API Evangelist annotations layered on top of the transcription —
  provenance, cross-links to the sibling artifacts in this repo, and the runtime-semantics warnings that
  the endpoint pages state in prose but that no OpenAPI field carries.
actions:
- target: $.info
  update:
    x-apievangelist-artifacts:
      conventions: conventions/asknicely-conventions.yml
      errors: errors/asknicely-problem-types.yml
      rate_limits: rate-limits/asknicely-rate-limits.yml
      authentication: authentication/asknicely-authentication.yml
      lifecycle: lifecycle/asknicely-lifecycle.yml
      changelog: changelog/asknicely-changelog.yml
      data_model: data-model/asknicely-data-model.yml
      webhooks: asyncapi/asknicely-webhooks.yml
      mcp: mcp/asknicely-mcp.yml
      examples: examples/asknicely-examples.yml
    x-apievangelist-spec-origin: transcribed-from-html-docs
    x-apievangelist-provider-publishes-openapi: false
- target: $.info
  update:
    x-apievangelist-idempotency:
      supported: false
      note: >-
        AskNicely documents no idempotency key. Contact writes upsert on email, but a repeated
        triggerSurvey can send a second survey. Retries on write operations are not safe by default.
- target: $.paths['/contact/trigger'].post
  update:
    x-apievangelist-warning: >-
      Two failure conditions (contact-rule suppression and unsubscribed contact) are returned as HTTP 200
      with success: true. Clients MUST inspect result[].survey_sent, not the status code.
    x-apievangelist-rate-limit:
      requests_per_10s: 100
      requests_per_60s: 500
      note: Lower than the account-wide limit. Batch into /contacts/add rather than retrying.
- target: $.paths['/contacts/add'].post
  update:
    x-apievangelist-async:
      since: '2021-07-01'
      note: >-
        Returns 201 immediately and processes afterwards. No job id, status endpoint or completion
        callback — verify by polling /contact/get. A retry after a timeout can double-process the batch.
- target: $.paths['/responses/{sortDirection}/{pagesize}/{pagenumber}/{sinceTime}/{format}'].get
  update:
    x-apievangelist-warning: >-
      Result sets above the redirect threshold (999 responses as of 2022-12-03, and AskNicely warns the
      number may change) are redirected to a temporary S3 file. A client that does not follow redirects
      silently gets nothing.
    x-apievangelist-filter-footgun: >-
      filters[] and values[] are paired BY POSITION. A count or order mismatch returns an empty result
      set rather than an error.
- target: $.paths['/contacts/deactivateall'].post
  update:
    x-apievangelist-warning: >-
      Destructive and account-wide — deactivates every contact. Returns 307 repeatedly until complete;
      the client must follow redirects. Contacts can be reactivated, but all scheduled sends stop.
    x-agentic-access:
      action-class: acting
      consequence: write
      human-in-the-loop: recommended
- target: $.paths['/privacy/remove'].post
  update:
    x-apievangelist-warning: >-
      Irreversible. Personal data is erased and the contact is added to the blocklist, so they can never
      be re-added or surveyed again. Never retry blindly and never expose to an agent unsupervised.
    x-agentic-access:
      action-class: acting
      consequence: safety-critical
      human-in-the-loop: required
- target: $.components.securitySchemes.apiKeyAuth
  update:
    x-apievangelist-note: >-
      AskNicely's help centre shows the key passed as a query-string parameter on /contact/trigger.
      Prefer the X-apikey header — a key in a URL leaks into logs, proxies and referrer headers. There is
      one key per user and it is account-wide in effect; there is no scoping or read-only key type.