API Evangelist enrichment overlay for the Tadeus Integration API

overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay for the Tadeus Integration API
  version: 1.0.0
x-provenance:
  generated: '2026-08-11'
  method: generated
  source: openapi/tadeus-api-integration-openapi.json
  note: >-
    Captures API Evangelist's enrichment of the Tadeus Integration API without mutating the
    harvested spec. Every value below is sourced from the provider's own published
    documentation (https://tadeus.net/api-examples, https://tadeus.net/mcp,
    https://tadeus.net/#pricing) or from a live probe recorded in this repo. Nothing is
    invented. The target spec is Swagger 2.0, so JSONPath targets use Swagger 2.0 node
    names (definitions, securityDefinitions) rather than OpenAPI 3 components.
extends: ../openapi/tadeus-api-integration-openapi.json
actions:
  - target: $.info
    description: Add contact, licence-free terms link and a real description.
    update:
      description: >-
        The Tadeus Integration API creates interview templates and campaigns, invites
        participants, and returns transcripts, structured results and AI-generated insights
        for AI-moderated voice interviews with a workforce. Authentication is a key pair
        sent as X-API-KEY-ID and X-API-SECRET headers on every request, generated in the
        Tadeus dashboard under API access. Responses are paginated with the Django REST
        Framework count/next/previous/results envelope.
      contact:
        name: Tadeus
        url: https://tadeus.net/contact
      termsOfService: https://tadeus.net/terms
      x-api-evangelist-notes:
        base_url_correction: >-
          The provider's published Python and cURL examples set BASE_URL to
          https://tadeus.net/api/integration/v1, which returns 404 with
          {"ok":false,"error":"not_found"}. The correct base, per this spec's own `host`
          field and verified live, is https://app.tadeus.net/api/integration/v1.
  - target: $.securityDefinitions.api_key
    description: >-
      Record that both key headers are required together, which the OR-semantics top-level
      security array understates.
    update:
      description: >-
        Key ID. MUST be sent together with the X-API-SECRET header — the two apiKey schemes
        are declared separately but are not alternatives.
      x-issued-at: Tadeus dashboard, "API access"
  - target: $.securityDefinitions.api_secret
    description: Same note on the secret half of the pair.
    update:
      description: >-
        Key secret. MUST be sent together with the X-API-KEY-ID header.
      x-issued-at: Tadeus dashboard, "API access"
  - target: $
    description: >-
      Attach the cross-cutting runtime semantics an agent needs and the contract does not
      state, all derived from artifacts in this repo.
    update:
      x-api-evangelist-conventions:
        pagination:
          style: page-number
          request_param: page
          response_fields: [count, next, previous, results]
        error_envelope:
          format: drf-detail
          shape: '{"detail": "string"}'
          rfc9457: false
          note: >-
            No 4xx or 5xx response is declared on any of the 47 operations in this spec.
        idempotency:
          supported: false
          note: >-
            No Idempotency-Key. Retrying campaigns_invite, campaigns_bulk_invite or
            campaigns_generate_insights after a timeout has undefined behaviour.
        rate_limits:
          documented: false
          headers: []
        transport:
          https_only: true
          tls: TLSv1.3
          hsts: false
      x-api-evangelist-agent-surface:
        mcp_server: https://app.tadeus.net/mcp
        mcp_gated: true
        published_tools: [search_transcripts, list_campaign_insights, get_campaign_stats]
        crosswalk: ../mcp/tadeus-api-tool-crosswalk.yml
      x-api-evangelist-regulatory:
        regime: EU AI Act (Regulation 2024/1689)
        posture: >-
          Workforce AI. Provider publishes a versioned self-classification arguing
          aggregate-only output keeps it outside Annex III point 4, and states that no
          emotion inference is performed (Article 5(1)(f)). Article 50 disclosure applies
          from 2026-08-02.
        documents: https://tadeus.net/trust
        note: >-
          Consumers embedding this API into a workforce platform inherit Article 26 deployer
          duties. See conformance/tadeus-api-conformance.yml.
  - target: $.paths['/campaigns/{uuid}/invite/'].post
    description: >-
      Flag a consequential, non-idempotent, outward-facing operation. Sourced from the
      provider's own example step 04.
    update:
      x-api-evangelist-consequence: high
      x-api-evangelist-note: >-
        Sends a real invitation to a real person and creates a session that consumes
        campaign quota. Not idempotent and has no idempotency key. An agent must not retry
        blind on timeout.
  - target: $.paths['/campaigns/{uuid}/bulk-invite/'].post
    description: Same flag, at cohort scale.
    update:
      x-api-evangelist-consequence: high
      x-api-evangelist-note: >-
        Invites an entire roster in one call — the provider's example describes a
        5,000-person rollout. No roster-size ceiling, no rate limit and no idempotency key
        are published. This is the single highest-blast-radius operation in the API.
  - target: $.paths['/campaigns/{uuid}/generate-insights/'].post
    description: Flag the billed asynchronous job.
    update:
      x-api-evangelist-consequence: medium
      x-api-evangelist-note: >-
        Starts a cross-session synthesis job that consumes processing minutes. Returns 201;
        no job id, status field or completion signal is documented, so the only way to know
        it finished is to poll insights_list.
  - target: $.paths['/sessions/'].post
    description: Record the privacy lever on session creation.
    update:
      x-api-evangelist-note: >-
        Setting email_capture_mode to "none" creates an anonymous session with no
        participant attached. This is the mechanism that keeps a deployment aggregate-only,
        which is the pivot of the provider's own EU AI Act classification argument.
  - target: $.definitions.Result
    description: Document the four quality signals an agent is meant to reason over.
    update:
      x-api-evangelist-note: >-
        confidence, relevance, sentiment and engagement are 0-1 signals about the RESPONSE,
        derived from what was said (comprehension, relevance, completion). The provider
        states explicitly that they are not voice-tone emotion inference and not profiles of
        people — the distinction its Article 5(1)(f) position rests on. output_json conforms
        to the customer-supplied output_schema on the Template.