# OpManager External APIs

A REST interface for integrating OpManager with third-party IT management and service desk software. Authenticate once, automate everything.

**Base URL**

`http://localhost:8060`

**Authentication**

`apikey` header

**Format**

JSON

**Specification**

OpenAPI 3.1.0 • API v1.0

[Download OpenAPI Spec (JSON)](https://www.manageengine.com/sites/meweb/json/itom/oas.json)

## Make your first request

Every request requires an API key, sent in the `apikey` header. Keys are unique per OpManager user account.

### 1. Enable REST API access

REST API access is **disabled by default**. An admin can enable it under **Settings > User Management** by editing the user.

### 2. Get your API key

Navigate to **Quick Links** in the OpManager web client to access your API key. The steps vary by version:

**v12.8.721+**

**Quick Links → API Key Management → Generate API key.**  
[Learn more](https://www.manageengine.com/network-monitoring/help/restapi/rest-api-opmanager.html#APIKeyManagement)

**Older versions**

**Quick Links → REST API Key** to view or copy your key.

### 3. Set the apikey header

Attach it to every request. Treat the key like a password — never commit it to source control.

### 4. Call any endpoint

All endpoints return JSON. Browse the OpenAPI spec for the full list of available operations.

### Request Example

#### cURL

```bash
curl -X GET "http://localhost:8060/api/json/device/listDevices" \
  -H "apikey: <your-api-key>"
```

#### JavaScript

```javascript
const res = await fetch(
  "http://localhost:8060/api/json/device/listDevices",
  { headers: { "apikey": "<your-api-key>" } }
);
const data = await res.json();
```

#### Python

```python
import requests

res = requests.get(
    "http://localhost:8060/api/json/device/listDevices",
    headers={"apikey": "<your-api-key>"},
)

devices = res.json()
```

### Sample Response

**200 OK**

```json
{
  "devices": [
    {
      "id": "10241",
      "name": "core-switch-01",
      "type": "Switch",
      "status": "Up"
    }
  ]
}
```

## API Key Management

From version **12.8.721**, OpManager provides a dedicated API Key Management interface that lets you generate, manage, and control access for multiple API keys.

### Accessing API Key Management

Navigate to **Quick Links → API Key Management** in the OpManager web client. This opens the management page listing all existing API keys along with their **Name**, **API Key**, **Description**, **Status**, **API Key Type**, **Created By**, **Expires On**, and **Access** toggle.

### Generating an API Key

Click the **Generate API key** button on the top-right of the API Key Management page. Fill in the following details:

- **Name** — A label for the API key.
- **Description** — A brief description of its purpose.
- **Expiry Date** — Check the box to set an expiry date; leave unchecked for a key that never expires.
- **API Key Type** — Choose between `Custom` or `MCP`.
- **Access Type** — Select one of the following:
  - **All Access** — The key grants access to all APIs available to the user.
  - **Module** — Restricts access based on selected modules. Each module can be set to *Read/Write*, *Read*, or *No Access* (default). The listed modules and permissions are based on your current user privileges.
  - **Specific API** — Restricts the key to individually selected API endpoints. A searchable list of available endpoints is displayed. You can search for specific endpoints or use *Select All*.

**Note:** The selected APIs will be accessible only if they are permitted for your user privileges.

### Managing Existing Keys

From the API Key Management listing page, each key can be:

- **Enabled or disabled** using the Access toggle.
- **Regenerated** using the refresh icon.
- **Deleted** using the delete icon.

**Note:** Super admins can view the created key list and can delete or revoke the keys, but cannot regenerate them.

### Sending the API Key (header)

```bash
curl -X GET "http://localhost:8060/api/json/device/listDevices" \
  -H "apikey: <your-api-key>"
```

## Rate Limiting

API endpoints enforce rate limits to protect server performance. Limits vary by endpoint — typically **500 requests per minute** for read operations and **100 requests per minute** for write/configuration operations. When the limit is exceeded, the API returns HTTP `429 Too Many Requests`. The rate limit for each endpoint is shown in its documentation below.

## HTTP Methods

OpManager APIs use the following HTTP methods:

- **GET** — Retrieve data
- **POST** — Add or create data and perform actions

## HTTP Status Codes

OpManager APIs return standard HTTP status codes to indicate success or failure:

| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded. Response body contains the requested data. |
| 400 | Bad Request | Invalid or missing request parameters. |
| 401 | Unauthorized | Missing or invalid API key. |
| 403 | Forbidden | The API key does not have permission for this operation. |
| 404 | Not Found | The requested resource or endpoint does not exist. |
| 429 | Too Many Requests | Rate limit exceeded. Wait before retrying. |
| 500 | Internal Server Error | Unexpected server-side error. Contact your administrator if this persists. |

### Response Format

All responses are returned in **JSON**. Successful operations typically return the requested data directly or wrapped in a `result` object.

#### Success response

```json
{
    "result": {
        "message": "Operation completed successfully"
    }
}
```

#### Error response

```json
{
    "error": {
        "code": 400,
        "message": "Invalid parameter value"
    }
}
```

## Pagination

List endpoints that return large datasets (e.g., `listDevices v2`) support pagination via `page` and `rows` query parameters. The response includes `total`, `page`, and `records` fields to help you iterate through results:

### Example — Paginated request

```http
GET /api/json/v2/device/listDevices?page=1&rows=200
```

## API Versioning

Some endpoints have multiple versions (e.g., `/api/json/admin/listDevices` and `/api/json/v2/device/listDevices`). Version 2 (`v2`) endpoints provide enhanced response formats, additional filtering, and pagination support. **Use v2 endpoints where available** for the best experience.

## Enterprise Edition (Central & Probe)

In **OpManager Enterprise Edition**, the Central server manages multiple Probes. Several API parameters are specific to this architecture:

- `eeProbeID` — Probe ID, required when querying a specific probe from Central.
- `probeName` — Name of the probe (from `listProbes` API response).

These parameters can be ignored when using OpManager **Standard or Professional** editions.

## MSP Edition

In **OpManager MSP Edition**, the Central server manages multiple customers and regions. The following API parameters are specific to MSP deployments:

- `selCustomerID` — Customer ID to scope requests to a specific customer. Set as `-1` when fetching data from Central.
- `regionID` — Region ID of the probe to scope requests to a specific region. Set as `-1` when fetching data from Central.

These parameters can be ignored when using OpManager **Standard, Professional, or Enterprise** editions.