API Evangelist enhancements for the ThreatDown OneView API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the ThreatDown OneView API
  version: 1.0.0
  x-generated: '2026-08-04'
  x-method: generated
  x-source: openapi/malwarebytes-threatdown-oneview-openapi.json
  x-note: >-
    Additive OpenAPI Overlay 1.0.0 capturing API Evangelist's enrichment of the harvested
    ThreatDown OneView definition. It never mutates the original file. OneView is the
    multi-tenant MSP projection of the same platform as Nebula, so it inherits the same
    error, pagination and rate-limit gaps, and adds a deprecated subscription surface.
extends: ../openapi/_original/malwarebytes-threatdown-oneview-openapi.json
actions:
- target: $.info
  description: Record provenance and the canonical spec location.
  update:
    contact:
      name: ThreatDown Support
      url: https://support.threatdown.com/hc/en-us/p/oneview
    x-spec-url: https://cloud.malwarebytes.com/api/v2/oneview/docs
    x-harvested: '2026-08-04'
    x-harvested-by: API Evangelist
    x-license-status: >-
      No licence or terms-of-service is declared in the definition. API use is governed by
      https://www.threatdown.com/legal/terms-of-service/.
    x-sibling-api: openapi/malwarebytes-threatdown-nebula-openapi.json
- target: $.info
  description: Surface the rate limit stated in prose but absent from the machine-readable definition.
  update:
    x-rate-limit:
      default: 360
      unit: requests
      interval: minute
      scope: per OAuth2 application
      algorithm: leaky bucket
      exceeded_status: 429
      headers_documented: false
      artifact: rate-limits/malwarebytes-rate-limits.yml
- target: $.info
  description: >-
    Record the error envelope observed live. The definition declares no 4xx or 5xx
    response on any of its 401 operations.
  update:
    x-error-envelope:
      media_type: application/json
      rfc9457: false
      shape:
        statusCode: integer
        error: string
        message: string
      artifact: errors/malwarebytes-problem-types.yml
- target: $.info
  description: Record the multi-tenant addressing model that distinguishes OneView from Nebula.
  update:
    x-tenancy:
      model: multi-tenant MSP
      tenant_param: account_id
      tenant_param_in: path
      used_on_operations: 141
      hierarchy_field: parent_account_id
      delegation_header: on-behalf-of
      delegation_used_on_operations: 7
      site_entity: >-
        A Site is the MSP-managed customer. It gains an account_id once a Subscription is
        attached, and that account_id is then used for all endpoint-security operations.
      artifact: data-model/malwarebytes-data-model.yml
- target: $.info
  description: >-
    Flag the deprecated subscription surface. The operations carry `deprecated: true` but
    no Sunset header, removal date, or replacement pointer.
  update:
    x-deprecations:
      count: 6
      sunset_header: false
      removal_date: null
      replacement_documented: false
      operations:
      - api.v2.oneview.create.subscription.id
      - api.v2.oneview.delete.subscription.id
      - api.v2.oneview.get.subscription.id
      - api.v2.oneview.update.subscription.id
      - api.v2.oneview.get.subscription.all
      - api.v2.oneview.get.master.subscription.id
      artifact: lifecycle/malwarebytes-lifecycle.yml
- target: $.info
  description: Record the cursor pagination contract and its inconsistencies.
  update:
    x-pagination:
      style: cursor
      request: [next_cursor, page_size]
      response: [next_cursor, total_count]
      inconsistency: >-
        A small number of operations still take `per_page` instead of `page_size`, and
        sorting uses sort_field/sort_direction here where Nebula uses sort_by/sort_order.
      artifact: conventions/malwarebytes-conventions.yml
- target: $.info
  description: Record that no request-idempotency mechanism exists.
  update:
    x-idempotency:
      supported: false
      header: null
      note: >-
        Site creation, user provisioning and job issuance are all non-idempotent. In a
        multi-tenant MSP context a retried Site creation can produce a duplicate customer.
- target: $.info
  description: Attach the webhook event catalog.
  update:
    x-event-catalog:
      artifact: asyncapi/malwarebytes-threatdown-webhooks.yml
      event_count: 18
      signature_header: X-MWB-Signature
      subscription_path: /oneview/v1/accounts/{account_id}/webhooks/subscriptions
      asyncapi_published: false
- target: $.components.securitySchemes.client_credentials
  description: Make the token endpoint absolute and record the two-gate authorization model.
  update:
    x-token-url-absolute: https://api.threatdown.com/oneview/oauth2/token
    x-declared-token-url: /oneview/oauth2/token
    x-actual-operation: api.oneview.oauth2.token
    x-authorization-model:
      gates:
      - name: oauth2 scope
        values: [read, write, execute]
      - name: user permission
        distinct_values: 84
      failure_status: 403
    x-scope-description-defect: >-
      The `read` scope description reads "Read data of your Nebula account" in the OneView
      definition — copied from Nebula and never adapted to Sites. Report upstream.
- target: $.info
  description: Record the structural review findings for this definition.
  update:
    x-api-evangelist-review:
      strengths:
      - 401 operations, each with a unique operationId, summary and description
      - Per-operation scope plus granular permission declared
      - Deprecated operations honestly flagged in the definition
      defects:
      - No 4xx or 5xx response declared on any operation.
      - components.schemas is empty; all schemas inlined, producing a 19.6 MB document.
      - >-
        The `authorization` header is declared as a plain required parameter on 400 of 401
        operations in addition to the securityScheme.
      - Scope descriptions still reference Nebula rather than OneView.
      - >-
        Six deprecated operations carry no Sunset header, no removal date and no
        replacement pointer.
      - No response examples anywhere in the definition.