API Evangelist enhancements for Authenticx AcxAPI

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Authenticx AcxAPI
  version: 1.0.0
extends: openapi/authenticx-acxapi-openapi.yml
x-generated: '2026-08-06'
x-method: generated
x-source: >-
  Derived from openapi/authenticx-acxapi-openapi.yml (harvested verbatim from
  https://api.beauthenticx.com/swagger/v1/swagger.json) plus the ReadMe docs hub. Every action below adds
  information to our copy of the spec; the harvested original in openapi/_original/ is never mutated.
actions:

# --- Contact + licence + description the published spec omits entirely -------------------------------------
- target: $.info
  update:
    description: >-
      Authenticx AcxAPI — REST API for uploading contact-center interactions (audio, chat, text), retrieving
      conversation insights, classifier and model results, transcriptions, QA evaluations, metadata, workflows
      and pharmacovigilance export receipts, plus agent/user/hierarchy/role administration and SCIM 2.0
      provisioning. OAuth 2.0 client credentials, scope `acxapi`.
    contact:
      name: Authenticx
      url: https://authenticx.readme.io/
    x-apievangelist-profile: https://apievangelist.com/
    x-apievangelist-harvested: '2026-08-06'
    x-apievangelist-source: https://api.beauthenticx.com/swagger/v1/swagger.json

# --- Both published environments, not just production ------------------------------------------------------
- target: $.servers
  update:
  - url: https://api.beauthenticx.com
    description: AcxApi Production Server
  - url: https://api.authcx.com
    description: AcxApi Experimental (staging) Server

# --- Declare the tag set the operations already use ---------------------------------------------------------
- target: $
  update:
    tags:
    - name: Conversations
      description: Conversation insights, classifier results and transcriptions.
    - name: Metadata
      description: The conversation record — the canonical carrier of conversation identity.
    - name: ModelResults
      description: ML predictions and human-review results, with export receipts and prior-result history.
    - name: Receipts
      description: Pharmacovigilance (PV) data reconciliation — receipts for exports to a downstream safety system.
    - name: Evaluations
      description: Quality-assurance evaluations and their scored modules.
    - name: Workflows
      description: Review workflow status per interaction and evaluation.
    - name: Media
      description: Audio and chat archive upload.
    - name: TextMedia
      description: Text and chat JSON upload.
    - name: Agent
      description: Contact-center agent administration.
    - name: User
      description: Platform user administration.
    - name: UserHierarchy
      description: Per-hierarchy permission grants for a user.
    - name: Hierarchy
      description: The organization tree that scopes conversations, agents and permissions.
    - name: Roles
      description: Read-only role and permission catalog.
    - name: Interactions
      description: DEPRECATED. Superseded by Conversations/Insights.
    - name: (Scim) Users
      description: SCIM 2.0 user provisioning (RFC 7643 / RFC 7644).
    - name: (Scim) Schemas
      description: SCIM 2.0 schema discovery.
    - name: (Scim) ResourceTypes
      description: SCIM 2.0 resource-type discovery.
    - name: (Scim) ServiceProviderConfig
      description: SCIM 2.0 service-provider capability discovery.

# --- Cross-cutting semantics captured in conventions/ -------------------------------------------------------
- target: $.info
  update:
    x-apievangelist-conventions:
      pagination:
        style: cursor
        params: [PageSize, LastId]
        casing_warning: GET /ModelResults uses lastId/pageSize; all other paged operations use LastId/PageSize.
        scim: startIndex + count (RFC 7644 3.4.2.4)
      idempotency:
        supported: false
        note: >-
          No idempotency key. POST /Media/Upload rejects duplicates on file-name uniqueness only, which is a
          constraint rather than an idempotency contract.
      errors:
        format: none
        note: No RFC 9457. 45 of 47 declared non-2xx responses carry no schema. SCIM errors use scim+json.
      rate_limits:
        published: false
        signal: 429 on POST /Media/Upload only; no Retry-After, no X-RateLimit-* headers.
      events:
        webhooks: false
        asyncapi: false
        note: Asynchronous processing completion is discovered by polling.
      conversation_identity:
        note: One conversation id travels the API under five field names.
        aliases:
          Metadata: Id
          Evaluations: Metadata.Id
          Insights: ConversationId
          Receipts: ConversationId
          Transcriptions: ConversationId (response) / conversationId (request)

# --- The largest single gap in the published spec: no operationId on any of 46 operations -------------------
- target: $.info
  update:
    x-apievangelist-findings:
    - id: no-operation-ids
      severity: high
      detail: >-
        All 46 operations lack operationId. Generated clients, MCP tools, Arazzo workflows and agent skills
        have no stable handle and must bind by METHOD + path.
    - id: no-error-schemas
      severity: high
      detail: >-
        Outside the SCIM subtree, no 4xx/5xx response declares a schema or media type — only a description
        string. Clients cannot branch programmatically on failure.
    - id: oidc-issuer-mismatch
      severity: medium
      detail: >-
        /.well-known/openid-configuration on api.beauthenticx.com advertises an issuer and endpoints on
        acxapi-net8d-prod1.azurewebsites.net, not on the branded host the docs tell integrators to call.
    - id: no-security-txt
      severity: medium
      detail: No /.well-known/security.txt on any Authenticx host; no published vulnerability disclosure policy.
    - id: undocumented-rate-limits
      severity: medium
      detail: 429 is declared but no quota, Retry-After, or rate-limit documentation exists.
    - id: no-sdks
      severity: medium
      detail: >-
        A 46-operation OpenAPI with no published client library in any registry; only copy-paste recipes.
    - id: no-deprecation-policy
      severity: low
      detail: >-
        Three operations and one field are flagged deprecated in-spec with named replacements, but there is no
        deprecation policy page, no sunset dates, and no RFC 8594 headers.

# --- Mark the deprecated surface with its replacement, machine-readably --------------------------------------
- target: $.paths['/Interactions'].get
  update:
    x-apievangelist-superseded-by: 'GET /Conversations/Insights'
- target: $.paths['/Interactions'].post
  update:
    x-apievangelist-superseded-by: 'POST /Conversations/Insights'
- target: $.paths['/Interactions/{AmdID}'].get
  update:
    x-apievangelist-superseded-by: 'GET /Conversations/Insights'

# --- Document the entitlement-gated and throttled operations --------------------------------------------------
- target: $.paths['/ModelResults/Conversation'].get
  update:
    x-apievangelist-entitlement: >-
      Returns 501 when the endpoint is not enabled for the calling organization. Treat 501 as a licensing
      signal, not a server fault.
- target: $.paths['/Media/Upload'].post
  update:
    x-apievangelist-throttled: >-
      The only operation in the API that declares 429. No Retry-After and no published quota; back off
      exponentially.
    x-apievangelist-duplicate-guard: >-
      A 400 'An interaction with this file name already exists.' on retry indicates the prior attempt
      succeeded. Treat that specific message as success, not failure.