Public API

Introduction

Bitdefender Control Center APIs allow developers to automate business workflows.

The APIs are exposed using JSON-RPC 2.0 protocol specified.

Each API call targets a method and passes a set of parameters.

There are two types of parameters:

required - MUST be always passed to the called method.
optional - has a default value and can be omitted from the parameters list. Any optional parameter can be skipped, regardless its position in the parameters list.

API requests

The API calls are performed as HTTP requests with JSON-RPC messages as payload. HTTP POST method MUST be used for each API call. Also, it is required that each HTTP request have the Content-Type header set to application/json.

Note

The API is limited to a specific number of requests per second per API key. If this limit is exceeded, subsequent requests are rejected and 429 HTTP status code is returned, along with a Retry-After header specifying the number of seconds left until you can send a new request.

Control Center exposes multiple APIs targeting distinct areas in the product. Each API exposes a set of methods related to a designated product area. The base URL for all APIs is the machine hostname, domain, or IP where GravityZone is installed: https://YOUR-HOSTNAME/api/v1.0/jsonrpc/. To obtain the full URL of the API, add the API name to the base URL.

Important

Ensure the access URL (or API endpoint, as it is universally known) is secure. Secure URLs always start with the https:// protocol.
If you are using an application to automate API usage, make sure it validates SSL/TLS certificates. This helps prevent man-in-the-middle type attacks.
Use up-to-date libraries or frameworks that support modern TLS protocols.

Currently, the following APIs are being exposed:

Accounts, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/accounts

General, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/general

Maintenance windows, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/maintenanceWindows

Network, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/network

Packages, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/packages

Policies, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/policies

Quarantine, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/quarantine

Reports, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/reports

Sandbox, with the API URL:

https://YOUR-HOSTNAME/api/v1.0/jsonrpc/sandbox

Sandbox Portal, with the API URL:
```
https://SANDBOX-IP/api/v1
```

The HTTP requests containing JSON RPC 2.0 can be performed on each API URL in order to consume the exposed functionality.

Note

Batch requests and notifications are not currently supported by Control Center.

API keys

You can generate personal API keys on the My account page. These API keys are tied to your Control Center account. For details, refer to Your account.

Authentication

The API calls to Control Center are authenticated at HTTP protocol level using the HTTP Basic Authentication mechanism described here.

The client application is required to send the Authorization request header each time it performs a call to an API.

The Authorization header consists of the following elements:

The authorization method and a space as the prefix; in our case, this will always be equal to Basic.
A Base64 encoded string, generated from the combined username:password sequence.
In our case, the API key is set as username, and password is set as an empty string.
For example, if the API Key is equal to
N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF, the Base64 encoding should be performed on the following string:
N8KzwcqVUxAI1RoPi5jyFJPkPlkDl9vF:. In this case, the content sent to the authorization header is
Basic TjhLendjcVZVeEFJMVJvUGk1anlGSlBrUGxrRGw5dkY6.

Error reporting

Control Center returns an error if the requested API method is unable to perform the desired task.

The error code and error message are returned as specified in JSON-RPC 2.0 Specification:

Error	Code	Message
Parse error	`-32700`	Parse error
Invalid request	`-32600`	Invalid Request
Method not found	`-32601`	Method not found
Invalid params	`-32602`	Invalid params
Server error	`-32000`	Server error
Authorization error - returned when the API request cannot be authenticated or the caller lacks permission. Covers invalid/missing API keys, insufficient API key scope, missing user rights, and license restrictions.	`-32001`	Authorization error
Resource not found - returned when the requested resource (incident, task, maintenance window, etc.) does not exist or is not accessible. For bulk queries, the details may list which specific IDs were not found.	`-32002`	Resource not found
Too many requests - returned with the `HTTP 429` status code (not `200` like other errors) when the caller exceeds the rate limit. The `Retry-After` response header indicates the number of seconds to wait before retrying. Limits are set per API key and may vary by method and subscription tier.	`-32003`	Too many requests

The full description of the error is placed in data.details member in the error message, as shown in the following examples:

Error response for a request that exceeds the scope of the API key:

{
  "id": "abc123",
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authorization error",
    "data": {
      "details": "API Key is not allowed to access the selected API: Incidents"
    }
  }
}

Error response for a request referencing a resource that does not exist or could not be found:

{
  "id": "abc123",
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "details": "There is no incident with the specified ID"
    }
  }
}

Error response when the rate limit is exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "id": "abc123",
  "jsonrpc": "2.0",
  "error": {
    "code": -32003,
    "message": "Too many requests",
    "data": {
      "details": "Rate limit exceeded. Maximum 100 requests per 60 seconds allowed. Try again later."
    }
  }
}

The HTTP status code is set according to the type of error:

HTTP status	Description
`401` Unauthorized	Authentication failed for the request (e.g. the API key is incorrect or missing).
`403` Forbidden	The request is not authorized to consume the desired functionality (e.g. the API is not enabled for the used API key).
`405` Method Not Allowed	The HTTP method is other than POST.
`429` Too Many Requests	More than 10 requests per second have been issued from the same API key.
`200` HTTP status code	Returned for successful requests or for requests that have failed due to server errors (e.g. a required parameter is not passed).

In this section:

Public API

Introduction

API requests

Note

Important

Note

API keys

Authentication

Error reporting

Search results