Malwarebytes Copilot API
The Copilot API from Malwarebytes — 10 operation(s) for copilot.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown Copilot API
description: '# Introduction
ThreatDown Nebula API lets you remotely manage the security of your `Endpoints`, analyze their `assets`, perform advanced analysis on `Detections` of `Malware`, `Ransomware`, `Exploits` and other threats found by the `ThreatDown Endpoint Agent`, and issue jobs like `Scan`, `Isolate`, `Remediate` or `Reboot`.
To get started, you need a client credential pair (OAuth2 application). You can get a valid application through our sales team.
You can retrieve your `client_id` and `client_secret` credentials pair in your Nebula console by going to the Integrate page in Nebula. You must also know your Nebula `account_id`.
## Cross-Origin Resource Sharing
This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with [W3C spec](https://www.w3.org/TR/cors/).
This allows cross-domain communication from the browser.
All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
## Authentication
ThreatDown API uses OAuth2, an open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.
See the Authentication section for specific information about supported grants.
## Access'' scopes
When creating a new application, you can decide the level of access it has to your account''s data. This utility allows you to restrict the scope of access to your account''s data depending on the application''s needs. For example, if you only need to analyze detections found on your endpoint, the read scope will be enough to prevent that application from modifying data or issuing jobs.
Specifying access scopes gives you more control over the access of your data. For example, you may want your company''s IT department to be able to isolate infected endpoints, while you may want your analysts to only read data for generating reports. To do so, you can create two applications using different scopes, and provide the right people with the right pair of credentials for programmatic access.
## User permissions
The user associated with the client (i.e. the user that created the OAuth2 application) must have the required permissions to perform the requested operation. If the user does not have sufficient permissions, the API will respond with a `403 Forbidden` status code.
For each API, you can find the required permissions in the AUTHORIZATIONS dropdown, under `user_permissions`.
Some API requires additional permissions based on the data in the body:
- **jobs** issue API requires `<entity>.performActions` depending on the `command` (\<entity\> can be `endpoints`, `softwareInventory`, or `detections`)
- **notifications** create/update API requires `<entity>.view` depending on the `category`
- **reports** create/update API requires `<entity>.view` depending on the `type`
## Rate Limiting
ThreatDown API implements a rate-limiting mechanism to prevent abuse. The rate-limiting mechanism is implemented using a leaky bucket algorithm. Once you exceed the available limit, our server will respond with a `429` status code. You can throttle your requests and retry them later.
The current limit, which you can see in the table below, has shown to be enough for most use cases. If you encounter `429` error codes, consider taking the following actions to minimize your APIs usage:
- Subscribe to webhooks events instead of polling the API for reacting to changes.
- Throttle the requests you send to the ThreatDown API for not exceeding the limit.
- Batch requests when possible.
- Contact us and request to increase the API quota for your application.
Currently, the default available quota is `360` requests per minute.
'
version: 1.0.0
x-logo:
altText: ThreatDown logo
url: https://assets.threatdown.com/hermes/ThreatDown_Horizontal_Navy.png
backgroundColor: '#FFFFFF'
servers:
- url: https://api.threatdown.com
tags:
- name: Copilot
paths:
/nebula/v1/copilot/chats/{id}/messages/{messageId}/action-confirm:
post:
description: Confirm Copilot chat action
summary: Confirm Copilot chat action
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.manage
status:
outage:
- auth
parameters:
- name: id
required: true
in: path
schema:
type: string
- name: messageId
required: true
in: path
schema:
type: number
- 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:
type: object
properties:
action:
type: string
description: Action to be confirmed
enum:
- apply_patches
- cancel_pending_tasks
- check_agent_updates
- check_protection_updates
- create_exclusions
- create_false_positive_request
- delete_endpoints
- delete_quarantined
- download
- edit_vulnerability_ignored
- generate_diagnostic_logs
- ignore_and_exclude
- ignore_vulnerability
- isolate_endpoints
- move_to_group
- quarantine_detection
- quarantine_threats
- remove_isolation
- restart_endpoints
- restore_and_exclude
- restore_quarantined
- restore_vulnerability_ignored
- scan_and_quarantine
- scan_and_report
- scan_custom
- scan_inventory
- uninstall_software
- update_agent
- update_application
- update_software
- sam.apply_patches
- sam.assign_firewall_policy
- sam.create_dns_rule
- sam.create_scheduled_scan
- sam.create_vpm_scheduled_scan
- sam.enable_browser_phishing_protection
- sam.enable_dns_rule
- sam.enable_firewall_policy
- sam.enable_mailbox_protection
- sam.initiate_investigation
- sam.initiate_remediation
- sam.initiate_scan
- sam.optimize_dns_rule
- sam.optimize_patch_management_policy
- sam.optimize_policy
- sam.optimize_scheduled_scan
- sam.optimize_vpm_scheduled_scan
- sam.optimize_vulnerability_assessment_policy
- sam.schedule_restart
- sam.setup_dkim
- sam.setup_dmarc
- sam.setup_report_phishing
- sam.setup_spf
- sam.update_agent
- sam.update_software
- sam.view_vulnerabilities
correlation_id:
type: string
format: uuid
description: Correlation ID associated with the confirmed action
score_impact:
type: number
description: Score impact of the action to be confirmed
minimum: 0
maximum: 100
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates whether the action was successfully confirmed
message:
type: string
description: Message
message_id:
type: number
description: The unique identifier of the message associated with the confirmed action
tags:
- Copilot
operationId: api.nebula.post.copilot.chats.id.messages.id.action.confirmation
/nebula/v1/copilot/chats/{id}:
delete:
description: Delete Copilot chat by ID.
summary: Delete Copilot chat by ID
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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:
- Copilot
operationId: api.nebula.delete.copilot.chats.id
get:
description: Get Copilot chat by ID.
summary: Get Copilot chat by ID
security:
- client_credentials:
- read
- user_permissions:
- threatdownAI.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: Chat Response
properties:
id:
type: string
description: Chat ID
user_id:
type: string
format: uuid
description: User ID
title:
type: string
description: Chat title
created_at:
type: string
title: Creation time
updated_at:
type: string
title: Last update time
messages:
type: array
description: List of messages in the chat
items:
type: object
title: Message response
properties:
message_id:
type: number
description: Unique identifier for the message
role:
type: string
description: Role of the message sender
content:
type: string
description: Content of the message
url_citations:
type:
- array
- 'null'
description: List of URL citations in the message
items:
type: object
properties:
url:
type: string
description: The URL of the citation
title:
type: string
description: The title of the cited page
orion_queries:
type:
- array
- 'null'
description: List of Orion queries in the message
items:
type: object
orion_queries_results:
type:
- array
- 'null'
feedback:
type:
- object
- 'null'
job_metadata:
type:
- object
- 'null'
description: Job metadata
handoff_status:
type:
- string
- 'null'
description: Status of the handoff, if applicable
candidate_action:
type:
- object
- 'null'
description: Candidate action suggested by the message
out_of_scope:
type: boolean
description: Indicates if the message content is out of scope
action_metadata:
type:
- object
- 'null'
description: Metadata related to the candidate action
additionalProperties: false
additionalProperties: false
tags:
- Copilot
operationId: api.nebula.get.copilot.chats.id
patch:
description: Rename an existing Copilot chat.
summary: Rename Copilot chat
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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: Rename Chat Request
type: object
required:
- title
properties:
title:
type: string
minLength: 1
description: The new title for the chat
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Rename Chat Response
properties:
id:
type: string
description: Chat ID
title:
type: string
description: Updated chat title
tags:
- Copilot
operationId: api.nebula.patch.copilot.chats.id
/nebula/v1/copilot/chats:
get:
description: Get Copilot chats.
summary: Get Copilot chats
security:
- client_credentials:
- read
- user_permissions:
- threatdownAI.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: array
title: Get Chats Response
items:
type: object
title: Chat Response
properties:
id:
type: string
description: Chat ID
user_id:
type: string
format: uuid
description: User ID
title:
type: string
description: Chat title
created_at:
type: string
title: Creation time
updated_at:
type: string
title: Last update time
messages:
type: array
description: List of messages in the chat
items:
type: object
title: Message response
properties:
message_id:
type: number
description: Unique identifier for the message
role:
type: string
description: Role of the message sender
content:
type: string
description: Content of the message
url_citations:
type:
- array
- 'null'
description: List of URL citations in the message
items:
type: object
properties:
url:
type: string
description: The URL of the citation
title:
type: string
description: The title of the cited page
orion_queries:
type:
- array
- 'null'
description: List of Orion queries in the message
items:
type: object
orion_queries_results:
type:
- array
- 'null'
feedback:
type:
- object
- 'null'
job_metadata:
type:
- object
- 'null'
description: Job metadata
handoff_status:
type:
- string
- 'null'
description: Status of the handoff, if applicable
candidate_action:
type:
- object
- 'null'
description: Candidate action suggested by the message
out_of_scope:
type: boolean
description: Indicates if the message content is out of scope
action_metadata:
type:
- object
- 'null'
description: Metadata related to the candidate action
additionalProperties: false
additionalProperties: false
tags:
- Copilot
operationId: api.nebula.get.copilot.chats
post:
description: Create a new Copilot chat.
summary: Create Copilot chat
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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 Chat Request
type: object
required:
- message
properties:
message:
type: string
minLength: 1
maxLength: 1000
description: The initial message to start the chat
title:
type: string
description: Optional title for the chat session
responses:
'202':
description: response schema
content:
application/json:
schema:
title: Create Chat Response
type: object
properties:
chat_id:
type: string
status:
type: string
tags:
- Copilot
operationId: api.nebula.post.copilot.chats
/nebula/v1/copilot/chats/{id}/followup:
get:
description: Get Copilot chat follow-up.
summary: Get Copilot chat follow-up
security:
- client_credentials:
- read
- user_permissions:
- threatdownAI.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: Get Chat followup response
properties:
questions:
type: array
items:
type: string
actions:
type: array
items:
type: string
tags:
- Copilot
operationId: api.nebula.get.copilot.chats.id.followup
/nebula/v1/copilot/quota:
get:
description: Get Copilot quota information.
summary: Get Copilot quota
security:
- client_credentials:
- read
- user_permissions:
- threatdownAI.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
properties:
account_id:
type: string
year_month:
type: string
message_count:
type: number
last_updated:
type: string
tags:
- Copilot
operationId: api.nebula.get.copilot.quota
/nebula/v1/copilot/chats/{id}/stream:
get:
description: Get Copilot chat stream.
summary: Get Copilot chat stream
security:
- client_credentials:
- read
- user_permissions:
- threatdownAI.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: Successful response
tags:
- Copilot
operationId: api.nebula.get.copilot.chats.id.stream
/nebula/v1/copilot/chats/{id}/message:
post:
description: Post a new message to an existing Copilot chat.
summary: Post message to Copilot chat
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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: Create Chat Request
type: object
required:
- message
properties:
message:
type: string
minLength: 1
maxLength: 1000
description: The initial message to start the chat
title:
type: string
description: Optional title for the chat session
responses:
'202':
description: response schema
content:
application/json:
schema:
title: Create Chat Response
type: object
properties:
chat_id:
type: string
status:
type: string
tags:
- Copilot
operationId: api.nebula.post.copilot.chats.id.message
/nebula/v1/copilot/chats/{id}/feedback:
post:
description: Post Copilot chat feedback.
summary: Post Copilot chat feedback
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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:
type: object
title: Submit feedback request
properties:
feedback_type:
type: string
enum:
- positive
- negative
- neutral
feedback_reason:
type: string
user_comment:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: Submit feedback response
properties:
feedback_id:
type: string
tags:
- Copilot
operationId: api.nebula.post.copilot.chats.id.feedback
/nebula/v1/copilot/chats/{id}/query-result:
post:
description: Post a query result to an existing Copilot chat.
summary: Post Copilot chat query result
security:
- client_credentials:
- write
- user_permissions:
- threatdownAI.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:
type: object
properties:
query_results:
type: array
items:
type: object
properties:
toolUseId:
type: string
response:
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-copilot-api-openapi.yml