claudetools/.claude/skills/bitdefender/references/api-reference.md

# Bitdefender GravityZone Cloud Public API Reference

Verified spec for the methods used by this skill. Sourced from Bitdefender's
archived Public API documentation. Methods are flagged **VERIFIED** (signature
confirmed and exposed in the CLI) or **UNVERIFIED** (signature not confirmed —
callable only via the generic `raw` subcommand, never exposed as a dedicated CLI
command).

---

## Connection

- **Base URL:** `https://cloud.gravityzone.bitdefender.com/api/v1.0/jsonrpc`
- **Module endpoint:** `<base>/<module>` (e.g. `.../jsonrpc/network`)
- **Auth:** HTTP Basic. Username = API key, password = empty string `""`.
- **Transport:** HTTPS POST, `Content-Type: application/json`.

### JSON-RPC envelope (request)

```json
{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "<methodName>",
  "params": { ...method params... }
}
```

### Response

- **Success:** body has a `result` field. The skill returns `body["result"]`.
- **Error:** body has an `error` object. The skill surfaces
  `error.data.details` if present, else `error.message`.

```json
{ "error": { "code": -32602, "message": "...", "data": { "details": "..." } } }
```

---

## ACG tenant IDs (hardcoded, partner root)

| Constant | Value | Meaning |
|---|---|---|
| `ACG_ROOT_COMPANY_ID` | `5c4280716c0318f3478b456a` | ACG partner company root |
| `ACG_COMPANIES_CONTAINER_ID` | `5c4280716c0318f3478b456e` | Container holding all client companies |

In `getNetworkInventoryItems` results, `type == 1` denotes a company node.

---

## general (`/general`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getApiKeyDetails` | `{}` | VERIFIED | Key scopes / rights. |

## licensing (`/licensing`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getLicenseInfo` | `{}` | VERIFIED | Seats, expiry, usage. |

## companies (`/companies`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getCompanyDetails` | `{}` or `{companyId}` | VERIFIED | Own company when no arg; a specific company when `companyId` given. |
| `getCompanyDetailsByUser` | uncertain | UNVERIFIED | Param shape not confirmed. Use `raw` if needed. |

## network (`/network`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getNetworkInventoryItems` | `parentId?, page?, perPage?, filters?` | VERIFIED | Inventory tree: companies/groups/endpoints. `type==1` = company. |
| `getEndpointsList` | `parentId?, page?, perPage<=100, filters?, options?` | VERIFIED | Endpoint list under a parent. `filters` supports name / OS / security status / policy. |
| `getManagedEndpointDetails` | `endpointId, options?` | VERIFIED | Full detail: `malwareStatus`, `agent{productVersion,engineVersion,signatureOutdated,productOutdated,lastUpdate}`, `modules`, `state`, `policy`, `companyId`, `lastSeen`. |
| `getScanTasksList` | `name?, status?, page?, perPage?` | VERIFIED | List scan tasks. |
| `createScanTask` | `targetIds[], type, name?, customScanSettings?` | VERIFIED | Start a scan. `type`: 1=Quick, 2=Full, 3=Memory, 4=Custom (verify against console). |
| `moveEndpoints` | `endpointIds[], groupId` | VERIFIED | Move endpoints into a group. |
| `createCustomGroup` | `name, parentId?` | VERIFIED | Create a custom group; returns new group id. |
| `deleteEndpoint` | `endpointId` | VERIFIED (destructive) | Remove an endpoint from inventory. CLI-gated behind `--confirm`. |
| `deleteCustomGroup` | `groupId` | VERIFIED (destructive) | Delete a custom group. CLI-gated behind `--confirm`. |
| `moveCustomGroup` | `groupId, newParentId` | VERIFIED | Re-parent a custom group. |
| `assignPolicy` | uncertain | UNVERIFIED | Assigns an EXISTING policy to endpoints. Param names not confirmed (likely `policyId` + a targets list). Do NOT use blindly — confirm against archived docs first. `raw` only. |
| `createReconfigureClientTask` | uncertain | UNVERIFIED | Param shape not confirmed. `raw` only. |
| `createUninstallTask` | uncertain | UNVERIFIED | Destructive; param shape not confirmed. `raw` only. |
| `setEndpointLabel` | uncertain | UNVERIFIED | Param shape not confirmed. `raw` only. |

## packages (`/packages`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getPackagesList` | `page?, perPage<=100` | VERIFIED | List installation packages. |
| `createPackage` | `packageName, companyId?, description?, language?, modules?, scanMode?, settings?, roles?, deploymentOptions?` | VERIFIED | Create an installer package. Returns the new package id. |
| `getInstallationLinks` | `packageName, companyId?` | VERIFIED | Returns Windows / Mac / Linux installer download URLs for a package. |
| `deletePackage` | `packageName, companyId?` | VERIFIED (destructive) | Delete a package. CLI-gated behind `--confirm`. |

## policies (`/policies`) — READ ONLY, SHALLOW

> **Important limitation:** The Public API exposes policies only at a shallow
> level. `getPolicyDetails` returns id / name / a limited subset of settings —
> **NOT** the granular module configuration shown in the console. There is **no
> create / edit / clone** policy method in the Public API. You can: list
> policies, read their names/ids, and (via the UNVERIFIED `assignPolicy`) assign
> an existing policy to endpoints. You CANNOT author or modify policy bodies
> programmatically.

| Method | Params | Status | Notes |
|---|---|---|---|
| `getPoliciesList` | `page?, perPage?` | VERIFIED | List policies (id, name). |
| `getPolicyDetails` | `policyId` | VERIFIED | Shallow detail only. Not the full config. |

## quarantine (`/quarantine`)

| Method | Params | Status | Notes |
|---|---|---|---|
| `getQuarantineItemsList` | `parentId, page, perPage, filters?` | VERIFIED | List quarantined items under a parent. |
| `createRemoveQuarantineItemTask` | uncertain | UNVERIFIED (destructive) | Param shape not confirmed. `raw` only. |
| `createRestoreQuarantineItemTask` | uncertain | UNVERIFIED | Param shape not confirmed. `raw` only. |

---

## Verified vs Unverified summary

**VERIFIED (CLI-exposed):**
general.getApiKeyDetails, licensing.getLicenseInfo, companies.getCompanyDetails,
network.getNetworkInventoryItems, network.getEndpointsList,
network.getManagedEndpointDetails, network.getScanTasksList,
network.createScanTask, network.createCustomGroup, network.moveEndpoints,
network.moveCustomGroup, network.deleteEndpoint (gated),
network.deleteCustomGroup (gated), packages.getPackagesList,
packages.createPackage, packages.getInstallationLinks, packages.deletePackage
(gated), policies.getPoliciesList, policies.getPolicyDetails,
quarantine.getQuarantineItemsList.

**UNVERIFIED (raw subcommand only — do NOT trust the param shape):**
network.assignPolicy, network.createReconfigureClientTask,
network.createUninstallTask, network.setEndpointLabel,
companies.getCompanyDetailsByUser, quarantine.createRemoveQuarantineItemTask,
quarantine.createRestoreQuarantineItemTask.

Confirm any UNVERIFIED signature against the official Bitdefender API reference
before relying on it. The generic `raw --module M --method m --params '<json>'`
subcommand can call any method once you know the correct params.