Manage governance rules and settings for AI Detection & Response (AIDR). Use these APIs to create per-tool authorization rules that determine whether specific AI tools are authorized, unauthorized, or pending review. Configure account-level defaults as a fallback when no matching rule exists.
openapi: 3.2.0
info:
title: Malwarebytes AI Detection & Response API
version: 1.0.0
description: 'Operations tagged AI Detection & Response across 2 of this provider''s published API definitions: malwarebytes-threatdown-nebula-openapi.json, malwarebytes-threatdown-oneview-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.threatdown.com
tags:
- name: AI Detection & Response
description: 'Manage governance rules and settings for AI Detection & Response (AIDR).
Use these APIs to create per-tool authorization rules that determine whether specific AI tools are authorized, unauthorized, or pending review. Configure account-level defaults as a fallback when no matching rule exists.
'
paths:
/nebula/v1/aidr/rules:
servers:
- url: https://api.threatdown.com
post:
description: Create a rule or default. Returns 409 if a rule with the same (tool, scope, category, policy_id) already exists for the account.
summary: Create AIDR rule
security:
- client_credentials:
- write
- user_permissions:
- aidr.manage
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
title: Create AIDR Rule
description: Create an AIDR per-tool or default governance rule
type: object
required:
- scope
- action
properties:
tool:
description: Canonical AI tool name. Omit or null for a default rule.
type:
- string
- 'null'
scope:
type: string
description: Targeting scope. "category" is only valid when tool is null.
enum:
- global
- policy
- category
category:
description: AI category. Required when scope = "category", must be absent otherwise.
type: string
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
description: Policy UUID. Required when scope = "policy", must be absent otherwise.
type: string
format: uuid
action:
type: string
description: Governance action.
enum:
- authorized
- unauthorized
- pending
allOf:
- description: scope=category requires tool=null and category to be a non-null string
if:
properties:
scope:
const: category
required:
- scope
then:
properties:
tool:
type: 'null'
required:
- category
- description: scope!=category requires category to be absent
if:
properties:
scope:
not:
const: category
required:
- scope
then:
not:
required:
- category
- description: scope=policy requires policy_id to be a non-null UUID string
if:
properties:
scope:
const: policy
required:
- scope
then:
properties:
policy_id:
type: string
format: uuid
required:
- policy_id
- description: scope!=policy requires policy_id to be absent
if:
properties:
scope:
not:
const: policy
required:
- scope
then:
not:
required:
- policy_id
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: AIDR Rule
description: A single AIDR governance rule or default. A rule with tool=null acts as a category or global default.
required:
- id
- account_id
- tool
- scope
- action
- created_at
- created_by
properties:
id:
type: string
format: uuid
description: Server-assigned rule UUID
account_id:
type: string
format: uuid
description: Account this rule belongs to. On a parent account, child account rules are included in GET responses.
tool:
type:
- string
- 'null'
description: AI tool name this rule targets. null = default rule applying to all tools (or all tools in a category).
scope:
type: string
description: '"global" applies to all policies. "policy" scopes the rule to a single policy_id. "category" is only valid when tool is null.'
enum:
- global
- policy
- category
category:
type: string
description: AI category (e.g. "AI Assistant"). Present only when scope is "category".
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
type: string
format: uuid
description: Policy UUID. Present only when scope is "policy".
action:
type: string
description: Governance action. "pending" is only valid when tool is null.
enum:
- authorized
- unauthorized
- pending
created_at:
type: string
description: ISO 8601 timestamp of rule creation
updated_at:
type:
- string
- 'null'
description: ISO 8601 timestamp of last update
created_by:
type: string
description: UUID of the user who created the rule
updated_by:
type:
- string
- 'null'
description: UUID of the user who last updated the rule
tags:
- AI Detection & Response
operationId: api.nebula.aidr.rules.post
get:
description: List rules and defaults for the account
summary: List AIDR rules
security:
- client_credentials:
- read
- user_permissions:
- aidr.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
- name: page_size
required: false
in: query
schema:
type: integer
- name: next_cursor
required: false
in: query
schema:
type: string
- name: filter[rule.tool][eq]
required: false
in: query
schema:
type: string
- name: filter[rule.tool][exists]
required: false
in: query
schema:
type: boolean
responses:
'200':
description: response schema
content:
application/json:
schema:
title: AIDR Rules Response
description: Paginated list of AIDR rules and defaults. When called on a parent account, includes rules for all child accounts.
type: object
required:
- rules
- total_count
properties:
rules:
type: array
items:
type: object
title: AIDR Rule
description: A single AIDR governance rule or default. A rule with tool=null acts as a category or global default.
required:
- id
- account_id
- tool
- scope
- action
- created_at
- created_by
properties:
id:
type: string
format: uuid
description: Server-assigned rule UUID
account_id:
type: string
format: uuid
description: Account this rule belongs to. On a parent account, child account rules are included in GET responses.
tool:
type:
- string
- 'null'
description: AI tool name this rule targets. null = default rule applying to all tools (or all tools in a category).
scope:
type: string
description: '"global" applies to all policies. "policy" scopes the rule to a single policy_id. "category" is only valid when tool is null.'
enum:
- global
- policy
- category
category:
type: string
description: AI category (e.g. "AI Assistant"). Present only when scope is "category".
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
type: string
format: uuid
description: Policy UUID. Present only when scope is "policy".
action:
type: string
description: Governance action. "pending" is only valid when tool is null.
enum:
- authorized
- unauthorized
- pending
created_at:
type: string
description: ISO 8601 timestamp of rule creation
updated_at:
type:
- string
- 'null'
description: ISO 8601 timestamp of last update
created_by:
type: string
description: UUID of the user who created the rule
updated_by:
type:
- string
- 'null'
description: UUID of the user who last updated the rule
total_count:
type: integer
description: Total number of rules matching the request (unpaginated)
tags:
- AI Detection & Response
operationId: api.nebula.aidr.rules.get
/nebula/v1/aidr/rules/{id}:
servers:
- url: https://api.threatdown.com
delete:
description: Delete a single AIDR rule or default
summary: Delete AIDR rule
security:
- client_credentials:
- write
- user_permissions:
- aidr.manage
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
description: Valid UUID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
responses:
'200':
description: Successful response
tags:
- AI Detection & Response
operationId: api.nebula.aidr.rules.delete
get:
description: Get a single AIDR rule or default by its UUID
summary: Get AIDR rule by ID
security:
- client_credentials:
- read
- user_permissions:
- aidr.view
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
description: Valid UUID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: AIDR Rule
description: A single AIDR governance rule or default. A rule with tool=null acts as a category or global default.
required:
- id
- account_id
- tool
- scope
- action
- created_at
- created_by
properties:
id:
type: string
format: uuid
description: Server-assigned rule UUID
account_id:
type: string
format: uuid
description: Account this rule belongs to. On a parent account, child account rules are included in GET responses.
tool:
type:
- string
- 'null'
description: AI tool name this rule targets. null = default rule applying to all tools (or all tools in a category).
scope:
type: string
description: '"global" applies to all policies. "policy" scopes the rule to a single policy_id. "category" is only valid when tool is null.'
enum:
- global
- policy
- category
category:
type: string
description: AI category (e.g. "AI Assistant"). Present only when scope is "category".
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
type: string
format: uuid
description: Policy UUID. Present only when scope is "policy".
action:
type: string
description: Governance action. "pending" is only valid when tool is null.
enum:
- authorized
- unauthorized
- pending
created_at:
type: string
description: ISO 8601 timestamp of rule creation
updated_at:
type:
- string
- 'null'
description: ISO 8601 timestamp of last update
created_by:
type: string
description: UUID of the user who created the rule
updated_by:
type:
- string
- 'null'
description: UUID of the user who last updated the rule
tags:
- AI Detection & Response
operationId: api.nebula.aidr.rules.get.id
put:
description: Replace all mutable fields of an existing AIDR rule or default
summary: Update AIDR rule
security:
- client_credentials:
- write
- user_permissions:
- aidr.manage
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
description: Valid UUID (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
title: Update AIDR Rule
description: Request body for replacing all mutable fields of an existing AIDR rule or default.
allOf:
- title: Create AIDR Rule
description: Create an AIDR per-tool or default governance rule
type: object
required:
- scope
- action
properties:
tool:
description: Canonical AI tool name. Omit or null for a default rule.
type:
- string
- 'null'
scope:
type: string
description: Targeting scope. "category" is only valid when tool is null.
enum:
- global
- policy
- category
category:
description: AI category. Required when scope = "category", must be absent otherwise.
type: string
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
description: Policy UUID. Required when scope = "policy", must be absent otherwise.
type: string
format: uuid
action:
type: string
description: Governance action.
enum:
- authorized
- unauthorized
- pending
allOf:
- description: scope=category requires tool=null and category to be a non-null string
if:
properties:
scope:
const: category
required:
- scope
then:
properties:
tool:
type: 'null'
required:
- category
- description: scope!=category requires category to be absent
if:
properties:
scope:
not:
const: category
required:
- scope
then:
not:
required:
- category
- description: scope=policy requires policy_id to be a non-null UUID string
if:
properties:
scope:
const: policy
required:
- scope
then:
properties:
policy_id:
type: string
format: uuid
required:
- policy_id
- description: scope!=policy requires policy_id to be absent
if:
properties:
scope:
not:
const: policy
required:
- scope
then:
not:
required:
- policy_id
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: AIDR Rule
description: A single AIDR governance rule or default. A rule with tool=null acts as a category or global default.
required:
- id
- account_id
- tool
- scope
- action
- created_at
- created_by
properties:
id:
type: string
format: uuid
description: Server-assigned rule UUID
account_id:
type: string
format: uuid
description: Account this rule belongs to. On a parent account, child account rules are included in GET responses.
tool:
type:
- string
- 'null'
description: AI tool name this rule targets. null = default rule applying to all tools (or all tools in a category).
scope:
type: string
description: '"global" applies to all policies. "policy" scopes the rule to a single policy_id. "category" is only valid when tool is null.'
enum:
- global
- policy
- category
category:
type: string
description: AI category (e.g. "AI Assistant"). Present only when scope is "category".
enum:
- AI Assistant
- AI Code Tool
- AI Framework & Local LLM
- AI Image & Video
- AI Meeting & Productivity
- AI Writing & Translation
policy_id:
type: string
format: uuid
description: Policy UUID. Present only when scope is "policy".
action:
type: string
description: Governance action. "pending" is only valid when tool is null.
enum:
- authorized
- unauthorized
- pending
created_at:
type: string
description: ISO 8601 timestamp of rule creation
updated_at:
type:
- string
- 'null'
description: ISO 8601 timestamp of last update
created_by:
type: string
description: UUID of the user who created the rule
updated_by:
type:
- string
- 'null'
description: UUID of the user who last updated the rule
tags:
- AI Detection & Response
operationId: api.nebula.aidr.rules.put
/nebula/v1/aidr/metadata:
servers:
- url: https://api.threatdown.com
get:
description: Returns all available AI tools and categories from the static AI whitelist
summary: Get AIDR metadata
security:
- client_credentials:
- read
- user_permissions:
- aidr.view
status:
outage:
- auth
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: AIDR Metadata
description: Enumerated AI tools and categories available for use in AIDR rule creation.
required:
- tools
- categories
properties:
tools:
type: array
description: Distinct canonical AI tool names from the AIDR metadata catalogue.
items:
type: string
categories:
type: array
description: Distinct AI tool category names from the AIDR metadata catalogue.
items:
type: string
tags:
- AI Detection & Response
operationId: api.nebula.aidr.metadata.get
/nebula/v1/aidr/tools/search:
servers:
- url: https://api.threatdown.com
post:
description: Search AI tools — one row per AI tool, combining software inventory and domain usage data.
summary: Search AI tools
security:
- client_credentials:
- read
- user_permissions:
- aidr.view
status:
outage:
- auth
- search_stateless
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: accountid
required: true
in: header
description: Your Nebula account id (Ex. "9256034b-7967-4253-a5d9-260663e4fa4f")
schema:
type: string
pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
requestBody:
content:
application/json:
schema:
title: AIDR Tools Search Schema
type: object
properties:
start_date:
type: string
title: Return records after this date (ISO 8601)
pattern: ^([0-9]+)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?(([Zz])|([\+|\-]([01][0-9]|2[0-3]):[0-5][0-9]))$
examples:
- '2026-04-07T00:00:00Z'
end_date:
type: string
title: Return records before this date (ISO 8601)
pattern: ^([0-9]+)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]|60)(\.[0-9]+)?(([Zz])|([\+|\-]([01][0-9]|2[0-3]):[0-5][0-9]))$
examples:
- '2026-05-07T00:00:00Z'
populate:
type: object
description: Optional server-side enrichment flags.
properties:
ai_status:
type: boolean
description: When true, orion evaluates AIDR rules from Postgres and adds ai_statuses to each tool item.
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Search AI tools response
required:
- tools
properties:
tools:
type: array
title: Per-tool aggregated stats
items:
type: object
properties:
ai_tool:
type: string
title: AI tool name
ai_category:
type: string
title: AI tool category
ai_risk:
type: string
vendor:
type: string
install_count:
type: integer
title: Number of machines with tool installed
last_detected:
type: string
format: date-time
title: Most recent detection from software inventory
min_installation_date:
type: string
format: date-time
title: Earliest installation date of the tool across the software inventory
query_count:
type: object
description: Domain-usage query count breakdown for the requested period
required:
- total
- authorized
- unauthorized
- pending
properties:
total:
type: integer
title: Total query count in the period
authorized:
type: integer
title: Authorized query count in the period
unauthorized:
type: integer
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-ai-detection-response-api-openapi.yml