Malwarebytes Subscriptions API
Subscriptions allow you to enable and manage ThreatDown security services for your customers by setting terms, volume and duration.
OpenAPI Specification
openapi: 3.2.0
info:
title: ThreatDown Subscriptions API
description: "# Introduction\nThreatDown OneView APIs provide you resources to remotely manage the security of your devices from code. It integrates ThreatDown protection into your workflows and pipelines. The following are some of the actions you can do with OneView APIs:\n\n- Manage the security of your endpoints.\n- Analyze endpoint assets.\n- Perform advance analysis on detections of malware, ransomware, exploits, and other threats by ThreatDown Endpoint Agent.\n- Scan, isolate, remediate, and reboot endpoints.\n- Create new sites.\n- Provision OneView users.\n- Create subscriptions for your customers.\n- Subscribe to security Webhook events to get notified of detections.\n\n## Authentication\n\nThreatDown API uses OAuth2 to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.\n\nRefer to the [Authentication](#operation/api.oneview.oauth2.token) endpoint to retrieve an `access_token` using your `client_id` and `client_secret`.\n\n## Access' scopes\n\nAccess scopes are the permissions that applications require for authorization and use. \n\nWhen creating a new application, you can decide the access level the application 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.\n\nSpecifying access scopes gives you control over the access of your data. You can set different scopes to provide the appropriate credentials to your team. 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.\n\nSee [Authentication](#operation/api.oneview.oauth2.token) for available scopes.\n\n## User permissions\n\nThe 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.\nFor each API, you can find the required permissions in the AUTHORIZATIONS dropdown, under `user_permissions`.\n\nSome API requires additional permissions based on the data in the body:\n- **jobs** issue API requires `<entity>.performActions` depending on the `command` (\\<entity\\> can be `endpoints`, `softwareInventory`, or `detections`)\n- **notifications** create/update API requires `<entity>.view` depending on the `category`\n- **reports** create/update API requires `<entity>.view` depending on the `type`\n\n## Getting Started\n\nAfter having obtained an `access_token`, you will be able to create [Sites](#tag/Sites) which you will be able to manage through apis.\n\nOnce you have created a customer, the next step is to use the [Subscription](#tag/Subscriptions) APIs to assign a valid subscription for your customer. This will attach an `account_id` property to your [Sites](#tag/Sites) resources that you can use for [Endpoints](#tag/Endpoints), [Detections](#tag/Detections), [Jobs](#tag/Jobs), [Webhooks](#tag/Webhooks) and other APIs for security management.\n\n## Rate Limiting\n\nThreatDown 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.\n\nThe 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:\n\n- Subscribe to webhooks events instead of polling the API for reacting to changes.\n- Throttle the requests you send to the ThreatDown API for not exceeding the limit.\n- Batch requests when possible.\n- Contact us and request to increase the API quota for your application.\n\nCurrently, the default available quota is `360` requests per minute.\n\n## Available catalog codes\n\nProtection:\n\n- `BUS-CLOUD-IR-01` - ThreatDown Incident Response\n- `BUS-CLOUD-EPP-01` - ThreatDown Endpoint Protection\n- `BUS-CLOUD-EPP-SER-01` - ThreatDown Endpoint Protection for Servers\n- `BUS-CLOUD-EPR-01` - ThreatDown Endpoint Detection and Response\n- `BUS-CLOUD-EDR-SER-01` - ThreatDown Endpoint Detection and Response for Servers\n- `BUS-MBCM-01` - ThreatDown Mobile Security for Business\n\nModules:\n\n- `BUS-MBVM-01` - ThreatDown Vulnerability Assessment\n- `BUS-MBVPM-01` - ThreatDown Vulnerability & Patch Management\n- `BUS-MBDNS-01` - ThreatDown DNS Filtering\n- `BUS-MBAB-01` - ThreatDown Application Block\n- `BUS-CLOUD-MDR-FR30-01` - MDR Data Retention - 30 days\n- `BUS-CLOUD-MDR-01` - ThreatDown Managed Detection and Response\n- `BUS-TDEMS-01` - Email Security\n"
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: Subscriptions
description: Subscriptions allow you to enable and manage ThreatDown security services for your customers by setting terms, volume and duration.
paths:
/oneview/v1/sites/{id}/subscriptions:
post:
description: 'Use this endpoint to create a subscription for one of your manages site. After creating one subscription, your customer''s data will be populated with an `account_id` field that you can use for security''s management apis, like detections, endpoints and jobs.
## Available catalog codes
| Catalog Code | Description |
| ---------------- | ------------------------------------------- |
| BUS-CLOUD-IR-01 | ThreatDown Incident Response |
| BUS-CLOUD-EPP-01 | ThreatDown Endpoint Protection |
| BUS-CLOUD-EPR-01 | ThreatDown Endpoint Protection And Response |
'
summary: Create subscription
deprecated: true
security:
- client_credentials:
- write
- user_permissions:
- sites.manage
status:
outage:
- auth
- ov
parameters:
- name: id
required: true
in: path
description: Valid OneView site ID (Ex. "30616562663436302D643733312D346238622D623338332D613031343538363566383333")
schema:
type: string
pattern: ^[A-Fa-f0-9]+$
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
requestBody:
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: The root schema
description: The root schema comprises the entire JSON document.
examples:
- catalog_code: BUS-CLOUD-EPP-01
volume_purchased: 7
term_length: 365
term_type: utility
required:
- catalog_code
- volume_purchased
- term_length
- term_type
additionalProperties: true
properties:
catalog_code:
type: string
title: The catalog_code schema
description: Product associated with this subscription
default: ''
enum:
- BUS-CLOUD-EPP-01
- BUS-CLOUD-EPR-01
- BUS-CLOUD-IR-01
- BUS-CLOUD-EPP-SER-01
- BUS-CLOUD-EDR-SER-01
examples:
- BUS-CLOUD-EPR-01
volume_purchased:
type: integer
title: Number of seats purchased
description: Amount of seats allocated for this subscription
default: 0
examples:
- 0
term_length:
type: integer
title: Length of duration
description: Length in days of the duration of the subscription
default: 0
examples:
- 0
term_type:
type: string
title: The term_type schema
description: Type of term for this subscription.
default: utility
emum:
- utility
- cloud_evaluation
examples:
- string
billing_duration:
type:
- string
- 'null'
title: The billing_duration schema
description: Recurrence of billing
default: monthly
enum:
- monthly
- annual
examples:
- monthly
billing_date:
type: integer
title: The billing_date schema
default: 0
examples:
- 0
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Payload returned when getting a subscription
description: get subscription response
examples:
- catalog_name: ThreatDown Incident Response
catalog_code: BUS-CLOUD-IR-01
volume_purchased: 1
volume_used: 0
status: active
term_type: utility
term_ends_on: '2022-01-16'
original_start_date: '2020-05-25T23:59:59.999+00:00'
term_length: 730
reset_count: '0'
billing_duration: monthly
billing_date: 0
version: 4759e32b938b86c20682f9e245fd885d
timestamp: '2020-05-25T11:49:41.063'
required:
- catalog_name
- catalog_code
- volume_purchased
- volume_used
- status
- term_type
- term_ends_on
- original_start_date
- term_length
- reset_count
properties:
catalog_name:
type: string
title: Catalog name
description: Friendly name indicating the purchased catalog
default: ''
examples:
- ThreatDown Incident Response
catalog_code:
type: string
title: Catalog code
description: 'Product associated with this subscription. Some of the possible values: BUS-CLOUD-IR-01, BUS-CLOUD-EPR-01, BUS-CLOUD-IR-01, BUS-CLOUD-EPP-SER-01, BUS-CLOUD-EDR-SER-01'
volume_purchased:
type: integer
title: Number of seats purchased
description: Amount of seats allocated for this subscription
default: 0
examples:
- 0
volume_used:
type: integer
title: Seats used
description: Amount of seats in use for this subscription
default: 0
examples:
- 0
status:
type: string
title: Status
description: Status of this subscription. 'active' when active.
default: ''
examples:
- active
term_type:
type: string
title: The term_type schema
description: Type of term for this subscription.
default: utility
emum:
- utility
- cloud_evaluation
examples:
- string
term_ends_on:
type: string
title: End of term
description: When the subscription expires. in format YYYY-mm-dd
default: ''
examples:
- '2022-01-16'
original_start_date:
type: string
title: Start of term
description: A timestamp of creation date for this subscription.
default: ''
examples:
- '2020-05-25T23:59:59.999+00:00'
term_length:
type: integer
title: Duration
description: Duration of subscription in days.
default: 0
examples:
- 730
reset_count:
type: string
title: Reset count
description: How many time the subscription was reset
default: ''
examples:
- '0'
billing_duration:
type:
- string
- 'null'
title: The billing_duration schema
description: Recurrence of billing
examples:
- monthly
- annual
- Usage
- Upfront
billing_date:
type: integer
title: The billing_date schema
default: 0
examples:
- 0
version:
type: string
title: Version
description: Hash of the version of this subscription. Useful for comparing changes occurred
default: ''
examples:
- 4759e32b938b86c20682f9e245fd885d
tags:
- Subscriptions
operationId: api.v2.oneview.create.subscription.id
delete:
description: Delete your site subscriptions. This will mark the subscription as expired
summary: Delete a subscription
deprecated: true
security:
- client_credentials:
- write
- user_permissions:
- sites.manage
status:
outage:
- auth
- ov
parameters:
- name: id
required: true
in: path
description: Valid OneView site ID (Ex. "30616562663436302D643733312D346238622D623338332D613031343538363566383333")
schema:
type: string
pattern: ^[A-Fa-f0-9]+$
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Delete subscription response schema
description: The expected response when deleting a subscription
examples:
- id: cc99c6bf-1610-43c1-a793-f955c098449c
deleted: true
required:
- id
- deleted
properties:
id:
type: string
title: UUID of the customer
description: The unique identifier of this customer.
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
deleted:
type: boolean
title: Status
description: Boolean indicating whether the subscription was deleted successfully or not.
default: ''
examples:
- true
tags:
- Subscriptions
operationId: api.v2.oneview.delete.subscription.id
get:
description: Get subscription data by site id.
summary: Get subscription
deprecated: true
security:
- client_credentials:
- read
- user_permissions:
- sites.view
status:
outage:
- auth
- ov
parameters:
- name: id
required: true
in: path
description: Valid OneView site ID (Ex. "30616562663436302D643733312D346238622D623338332D613031343538363566383333")
schema:
type: string
pattern: ^[A-Fa-f0-9]+$
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Payload returned when getting a subscription
description: get subscription response
examples:
- catalog_name: ThreatDown Incident Response
catalog_code: BUS-CLOUD-IR-01
volume_purchased: 1
volume_used: 0
status: active
term_type: utility
term_ends_on: '2022-01-16'
original_start_date: '2020-05-25T23:59:59.999+00:00'
term_length: 730
reset_count: '0'
billing_duration: monthly
billing_date: 0
version: 4759e32b938b86c20682f9e245fd885d
timestamp: '2020-05-25T11:49:41.063'
required:
- catalog_name
- catalog_code
- volume_purchased
- volume_used
- status
- term_type
- term_ends_on
- original_start_date
- term_length
- reset_count
properties:
catalog_name:
type: string
title: Catalog name
description: Friendly name indicating the purchased catalog
default: ''
examples:
- ThreatDown Incident Response
catalog_code:
type: string
title: Catalog code
description: 'Product associated with this subscription. Some of the possible values: BUS-CLOUD-IR-01, BUS-CLOUD-EPR-01, BUS-CLOUD-IR-01, BUS-CLOUD-EPP-SER-01, BUS-CLOUD-EDR-SER-01'
volume_purchased:
type: integer
title: Number of seats purchased
description: Amount of seats allocated for this subscription
default: 0
examples:
- 0
volume_used:
type: integer
title: Seats used
description: Amount of seats in use for this subscription
default: 0
examples:
- 0
status:
type: string
title: Status
description: Status of this subscription. 'active' when active.
default: ''
examples:
- active
term_type:
type: string
title: The term_type schema
description: Type of term for this subscription.
default: utility
emum:
- utility
- cloud_evaluation
examples:
- string
term_ends_on:
type: string
title: End of term
description: When the subscription expires. in format YYYY-mm-dd
default: ''
examples:
- '2022-01-16'
original_start_date:
type: string
title: Start of term
description: A timestamp of creation date for this subscription.
default: ''
examples:
- '2020-05-25T23:59:59.999+00:00'
term_length:
type: integer
title: Duration
description: Duration of subscription in days.
default: 0
examples:
- 730
reset_count:
type: string
title: Reset count
description: How many time the subscription was reset
default: ''
examples:
- '0'
billing_duration:
type:
- string
- 'null'
title: The billing_duration schema
description: Recurrence of billing
examples:
- monthly
- annual
- Usage
- Upfront
billing_date:
type: integer
title: The billing_date schema
default: 0
examples:
- 0
version:
type: string
title: Version
description: Hash of the version of this subscription. Useful for comparing changes occurred
default: ''
examples:
- 4759e32b938b86c20682f9e245fd885d
tags:
- Subscriptions
operationId: api.v2.oneview.get.subscription.id
put:
description: Use this endpoint to upgrade/downgrade or change term types or seats
summary: Update webhook subscription
deprecated: true
security:
- client_credentials:
- write
- user_permissions:
- sites.manage
status:
outage:
- auth
- ov
parameters:
- name: id
required: true
in: path
description: Valid OneView site ID (Ex. "30616562663436302D643733312D346238622D623338332D613031343538363566383333")
schema:
type: string
pattern: ^[A-Fa-f0-9]+$
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
requestBody:
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: The root schema
description: The root schema comprises the entire JSON document.
examples:
- catalog_code: BUS-CLOUD-EPP-01
volume_purchased: 7
term_length: 365
term_type: utility
required:
- catalog_code
- volume_purchased
- term_length
- term_type
additionalProperties: true
properties:
catalog_code:
type: string
title: The catalog_code schema
description: Product associated with this subscription
default: ''
enum:
- BUS-CLOUD-EPP-01
- BUS-CLOUD-EPR-01
- BUS-CLOUD-IR-01
- BUS-CLOUD-EPP-SER-01
- BUS-CLOUD-EDR-SER-01
examples:
- BUS-CLOUD-EPR-01
volume_purchased:
type: integer
title: Number of seats purchased
description: Amount of seats allocated for this subscription
default: 0
examples:
- 0
term_length:
type: integer
title: Length of duration
description: Length in days of the duration of the subscription
default: 0
examples:
- 0
term_type:
type: string
title: The term_type schema
description: Type of term for this subscription.
default: utility
emum:
- utility
- cloud_evaluation
examples:
- string
billing_duration:
type:
- string
- 'null'
title: The billing_duration schema
description: Recurrence of billing
default: monthly
enum:
- monthly
- annual
examples:
- monthly
billing_date:
type: integer
title: The billing_date schema
default: 0
examples:
- 0
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Payload returned when getting a subscription
description: get subscription response
examples:
- catalog_name: ThreatDown Incident Response
catalog_code: BUS-CLOUD-IR-01
volume_purchased: 1
volume_used: 0
status: active
term_type: utility
term_ends_on: '2022-01-16'
original_start_date: '2020-05-25T23:59:59.999+00:00'
term_length: 730
reset_count: '0'
billing_duration: monthly
billing_date: 0
version: 4759e32b938b86c20682f9e245fd885d
timestamp: '2020-05-25T11:49:41.063'
required:
- catalog_name
- catalog_code
- volume_purchased
- volume_used
- status
- term_type
- term_ends_on
- original_start_date
- term_length
- reset_count
properties:
catalog_name:
type: string
title: Catalog name
description: Friendly name indicating the purchased catalog
default: ''
examples:
- ThreatDown Incident Response
catalog_code:
type: string
title: Catalog code
description: 'Product associated with this subscription. Some of the possible values: BUS-CLOUD-IR-01, BUS-CLOUD-EPR-01, BUS-CLOUD-IR-01, BUS-CLOUD-EPP-SER-01, BUS-CLOUD-EDR-SER-01'
volume_purchased:
type: integer
title: Number of seats purchased
description: Amount of seats allocated for this subscription
default: 0
examples:
- 0
volume_used:
type: integer
title: Seats used
description: Amount of seats in use for this subscription
default: 0
examples:
- 0
status:
type: string
title: Status
description: Status of this subscription. 'active' when active.
default: ''
examples:
- active
term_type:
type: string
title: The term_type schema
description: Type of term for this subscription.
default: utility
emum:
- utility
- cloud_evaluation
examples:
- string
term_ends_on:
type: string
title: End of term
description: When the subscription expires. in format YYYY-mm-dd
default: ''
examples:
- '2022-01-16'
original_start_date:
type: string
title: Start of term
description: A timestamp of creation date for this subscription.
default: ''
examples:
- '2020-05-25T23:59:59.999+00:00'
term_length:
type: integer
title: Duration
description: Duration of subscription in days.
default: 0
examples:
- 730
reset_count:
type: string
title: Reset count
description: How many time the subscription was reset
default: ''
examples:
- '0'
billing_duration:
type:
- string
- 'null'
title: The billing_duration schema
description: Recurrence of billing
examples:
- monthly
- annual
- Usage
- Upfront
billing_date:
type: integer
title: The billing_date schema
default: 0
examples:
- 0
version:
type: string
title: Version
description: Hash of the version of this subscription. Useful for comparing changes occurred
default: ''
examples:
- 4759e32b938b86c20682f9e245fd885d
tags:
- Subscriptions
operationId: api.v2.oneview.update.subscription.id
/oneview/v1/sites/{id}/subscriptions/all:
get:
description: Get all subscriptions data by site id.
summary: Get all subscriptions
deprecated: true
security:
- client_credentials:
- read
- user_permissions:
- sites.view
status:
outage:
- auth
- ov
parameters:
- name: id
required: true
in: path
description: Valid OneView site ID (Ex. "30616562663436302D643733312D346238622D623338332D613031343538363566383333")
schema:
type: string
pattern: ^[A-Fa-f0-9]+$
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Payload returned when getting a subscription
description: get subscription response
examples:
- catalog
# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-subscriptions-api-openapi.yml