Create and manage sites through APIs. Using sites APIs you can easily segment the usage and the subscriptions for your customers. In order to obtain an `account_id` for one of your sites to use for security APIs, for example [Endpoints](#tag/Endpoints) and [Installers](#tag/Installers), you need to create first a valid [Subscription](#tag/Subscriptions) for your customer.
openapi: 3.2.0
info:
title: ThreatDown Sites 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: Sites
description: 'Create and manage sites through APIs. Using sites APIs you can easily segment the usage and the subscriptions for your customers.
In order to obtain an `account_id` for one of your sites to use for security APIs, for example [Endpoints](#tag/Endpoints) and [Installers](#tag/Installers), you need to create first a valid [Subscription](#tag/Subscriptions) for your customer.'
paths:
/oneview/v1/sites:
post:
description: Create a new OneView site
summary: Create new site
security:
- client_credentials:
- write
- user_permissions:
- sites.create
status:
outage:
- auth
- ov
parameters:
- 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: Payload for creating one site
description: ''
examples:
- company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- bensley@company.com
site_end_date: string
required:
- company_name
- firstname
- lastname
- email
- account_owner
properties:
company_name:
type: string
title: Name of the customer
description: The name of your customer. Friendly name to associate to the account created.
default: ''
examples:
- string
firstname:
type: string
title: First name of responsible
description: First name of the contact
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the contact.
default: ''
examples:
- Ensley
email:
type: string
title: Email
description: Email address of the contact
default: ''
examples:
- bensley@company.it
account_owner:
type: array
title: Owner of the account
description: The email(s) of the owner(s) of this account.
default: []
examples:
- - boss@company.it
site_end_date:
type: string
title: End of site in yyyy-mm-dd format (Ex. "2021-05-02")
pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
examples:
- '2021-05-02'
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Site response schema
description: The expected response when getting a site
examples:
- id: cc99c6bf-1610-43c1-a793-f955c098449c
company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- mensley@company.com
site_end_date: '2021-05-02'
required:
- id
- company_name
- firstname
- lastname
- email
- account_owner
properties:
id:
type: string
title: UUID of the customer
description: The unique identifier of this customer.
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
company_name:
type: string
title: Name of the customer
description: The name of your customer. Friendly name to associate to the account created.
default: ''
examples:
- string
firstname:
type: string
title: First name of responsible
description: First name of the contact
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the contact.
default: ''
examples:
- Ensley
email:
type: string
title: Email
description: Email address of the contact
default: ''
examples:
- bensley@company.it
account_owner:
type: array
title: Owner of the account
description: The email(s) of the owner(s) of this account.
items:
type: string
default: []
examples:
- - boss@company.it
site_end_date:
type: string
title: End of customer in yyyy-mm-dd format (Ex. "2021-05-02")
pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
examples:
- '2021-05-02'
tags:
- Sites
operationId: api.oneview.create.customer
get:
description: Get a list of all your managed sites
summary: Get all sites
security:
- client_credentials:
- read
- user_permissions:
- sites.view
status:
outage:
- auth
- ov
parameters:
- name: authorization
required: true
in: header
description: Authorization token
schema:
type: string
- name: id
required: false
in: query
schema:
type: string
- name: company_name
required: false
in: query
schema:
type: string
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Customer response schema
description: The expected response when getting all sites
examples:
- sites:
id: cc99c6bf-1610-43c1-a793-f955c098449c
company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- mensley@company.com
site_end_date: '2021-05-02'
properties:
sites:
type: array
items:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Site response schema
description: The expected response when getting a site
examples:
- id: cc99c6bf-1610-43c1-a793-f955c098449c
company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- mensley@company.com
site_end_date: '2021-05-02'
required:
- id
- company_name
- firstname
- lastname
- email
- account_owner
properties:
id:
type: string
title: UUID of the site
description: The unique identifier of this site.
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
account_id:
type: string
title: UUID of the account
description: Unique identifier for accessing security resources associated to this site, like endpoints and detections. You need to create a valid subscription to see this field
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
cloud_evaluation:
type: boolean
title: Cloud Evaluation
description: True if the account is valid for cloud evaluation
default: ''
examples:
- true
account_status:
type: string
title: Status
description: Status of the account. 'ACTIVE' for a live account with valid subscription
default: ''
examples:
- NOT_APPLICABLE
company_name:
type: string
title: Name of the site
description: The name of your customer. Friendly name to associate to the account created.
default: ''
examples:
- string
firstname:
type: string
title: First name of responsible
description: First name of the contact
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the contact.
default: ''
examples:
- Ensley
email:
type: string
title: Email
description: Email address of the contact
default: ''
examples:
- bensley@company.it
account_owner:
type: array
title: Owner of the account
description: The email(s) of the owner(s) of this account.
items:
type: object
examples:
- id: fe366ce017519c74c3f1b2655ae1075b
email: oneviewuser@domain.it
firstname: Bob
lastname: Alice
roles:
- Administrator
required:
- id
- email
- firstname
- lastname
- roles
properties:
id:
type: string
title: UUID
description: The unique identifier of the account owner.
default: ''
examples:
- fe366ce017519c74c3f1b2655ae1075b
email:
type: string
title: Email
description: The email of the owner of the account
default: ''
examples:
- aensley.ygi2bhac-qa-@yopmail.com
firstname:
type: string
title: First Name
description: First name of the account owner.
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the account owner
default: ''
examples:
- Smith
roles:
anyOf:
- type: array
items:
type: string
- type: 'null'
title: Roles
description: The role(s) of the owener of the account
default: []
examples:
- - Administrator
site_end_date:
type: string
title: End of site in yyyy-mm-dd format (Ex. "2021-05-02")
pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
examples:
- '2021-05-02'
tags:
- Sites
operationId: api.oneview.get.all.customers
/oneview/v1/sites/{id}:
delete:
description: Delete a OneView site
summary: Delete site
security:
- client_credentials:
- write
- user_permissions:
- sites.delete
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: Customer response schema
description: The expected response when deleting a customer
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 customer was deleted successfully or not.
default: ''
examples:
- true
tags:
- Sites
operationId: api.oneview.delete.customer
get:
description: Get one site by its unique identifier
summary: Get site by ID
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: Site response schema
description: The expected response when getting a site
examples:
- id: cc99c6bf-1610-43c1-a793-f955c098449c
company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- mensley@company.com
site_end_date: '2021-05-02'
required:
- id
- company_name
- firstname
- lastname
- email
- account_owner
properties:
id:
type: string
title: UUID of the site
description: The unique identifier of this site.
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
account_id:
type: string
title: UUID of the account
description: Unique identifier for accessing security resources associated to this site, like endpoints and detections. You need to create a valid subscription to see this field
default: ''
examples:
- cc99c6bf-1610-43c1-a793-f955c098449c
cloud_evaluation:
type: boolean
title: Cloud Evaluation
description: True if the account is valid for cloud evaluation
default: ''
examples:
- true
account_status:
type: string
title: Status
description: Status of the account. 'ACTIVE' for a live account with valid subscription
default: ''
examples:
- NOT_APPLICABLE
company_name:
type: string
title: Name of the site
description: The name of your customer. Friendly name to associate to the account created.
default: ''
examples:
- string
firstname:
type: string
title: First name of responsible
description: First name of the contact
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the contact.
default: ''
examples:
- Ensley
email:
type: string
title: Email
description: Email address of the contact
default: ''
examples:
- bensley@company.it
account_owner:
type: array
title: Owner of the account
description: The email(s) of the owner(s) of this account.
items:
type: object
examples:
- id: fe366ce017519c74c3f1b2655ae1075b
email: oneviewuser@domain.it
firstname: Bob
lastname: Alice
roles:
- Administrator
required:
- id
- email
- firstname
- lastname
- roles
properties:
id:
type: string
title: UUID
description: The unique identifier of the account owner.
default: ''
examples:
- fe366ce017519c74c3f1b2655ae1075b
email:
type: string
title: Email
description: The email of the owner of the account
default: ''
examples:
- aensley.ygi2bhac-qa-@yopmail.com
firstname:
type: string
title: First Name
description: First name of the account owner.
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the account owner
default: ''
examples:
- Smith
roles:
anyOf:
- type: array
items:
type: string
- type: 'null'
title: Roles
description: The role(s) of the owener of the account
default: []
examples:
- - Administrator
site_end_date:
type: string
title: End of site in yyyy-mm-dd format (Ex. "2021-05-02")
pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
examples:
- '2021-05-02'
tags:
- Sites
operationId: api.oneview.get.customer
put:
description: Update a OneView site
summary: Update site
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: Payload for updating one site
description: ''
examples:
- company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- bensley@company.com
site_end_date: string
required:
- company_name
- firstname
- lastname
- email
- account_owner
properties:
company_name:
type: string
title: Name of the site
description: The name of your site. Friendly name to associate to the account created.
default: ''
examples:
- string
firstname:
type: string
title: First name of responsible
description: First name of the contact
default: ''
examples:
- Bob
lastname:
type: string
title: Last name
description: Last name of the contact.
default: ''
examples:
- Ensley
email:
type: string
title: Email
description: Email address of the contact
default: ''
examples:
- bensley@company.it
account_owner:
type: array
title: Owner of the account
description: The email(s) of the owner(s) of this account.
default: []
examples:
- - boss@company.it
site_end_date:
type: string
title: End of customer in yyyy-mm-dd format (Ex. "2021-05-02")
pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$
examples:
- '2021-05-02'
responses:
'200':
description: response schema
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: Site response schema
description: The expected response when updating a site
examples:
- id: cc99c6bf-1610-43c1-a793-f955c098449c
company_name: Malwarebytes Inc.
firstname: Bob
lastname: Ensley
email: bensley@company.com
account_owner:
- mensley@company.com
site_end_date: '2021-05-02'
required:
- id
- company_name
- firstname
- lastname
- email
- account_owner
properties:
id:
type: string
title: UUID of the customer
description: The uniqu
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/malwarebytes/refs/heads/main/openapi/malwarebytes-sites-api-openapi.yml