Using the OTbase Discovery Manager REST API

With v17.6, OTbase Discovery Manager includes a REST API. You can use it to automate Manager tasks from scripts and other software: organize the nodes registered in Manager, run operations on selected nodes or groups, inspect results, and maintain Manager settings. The API uses the Manager HTTPS port.

Connect to Discovery Manager at https://<manager-host>:<port>/api/v1. The default HTTPS port is 443. The examples use manager.example as a placeholder host; add :<port> to the URL if your Manager uses a different port.

All paths begin with /api/v1. JSON property names use lowerCamelCase.

Log in to Manager

$login = @{ username = 'manager-user'; password = 'manager-password' } |
  ConvertTo-Json -Compress
$session = $login | curl.exe 'https://manager.example/api/v1/sessions' `
  -H 'Content-Type: application/json' --data-binary '@-' | ConvertFrom-Json
$token = $session.accessToken

The response is 201:

{"accessToken":"session-token","tokenType":"Bearer","expiresIn":60}

Send Authorization: Bearer <accessToken> with subsequent requests. JSON bodies need Content-Type: application/json.

For example, list the nodes registered in Manager:

curl.exe 'https://manager.example/api/v1/nodes' `
  -H "Authorization: Bearer $token"

An idle session expires after 60 seconds. Sessions also expire after eight hours, once any active requests, transfers, or jobs finish. Log in again after expiry. Session list IDs cannot be used as access tokens.

Node credentials

If a node needs different login credentials, supported operations accept:

X-OTbase-Node-Authorization: Basic <base64(username:password)>

Keep the Manager bearer token in Authorization. Account operations use their JSON login fields; backup creation uses the configured backup credentials.

Batches

Batch requests for existing nodes select with nodeIds, groupIds, or both:

{"nodeIds":["node-a"],"groupIds":["group-b"]}

• groupIds selects the nodes in those groups; duplicate nodes are processed once.
• Without either field, all configured nodes are selected.
• For batch actions with a body, put the selection in URL query parameters or in the JSON body (in the manifest for multipart uploads).
• GET has no request body, so its selection goes only in URL query parameters.
• Repeat nodeIds and groupIds in the URL to select multiple IDs.
• Import takes new node definitions instead of an existing-node selection.

Each node has its own result. Check results even when the response is 200:

{
  "results":[
    {"index":0,"nodeId":"node-a","status":204},
    {"index":1,"nodeId":"node-b","status":404,"error":"node_not_found","message":"The requested node was not found."}
  ],
  "summary":{"total":2,"succeeded":1,"failed":1}
}

Some actions return 202 when at least one node starts background work.

For example, start a probe on two registered nodes without waiting for it to finish:

$selection = @{ nodeIds = @('node-a', 'node-b') } | ConvertTo-Json -Compress
$selection | curl.exe -X PUT `
  'https://manager.example/api/v1/batch/nodes/doProbe?wait=false' `
  -H "Authorization: Bearer $token" `
  -H 'Content-Type: application/json' --data-binary '@-'

Nodes and groups

For node PUT, host is required; omitted port defaults to 44461 and backupEnabled to false. Node PATCH leaves omitted fields unchanged.

Create a node with an existing group ID:

{"host":"node.example","port":44461,"groupId":"group-id","product":"Discovery Server"}

product defaults to Discovery Server; Discovery Agent is also supported. Each node belongs to one group. Nodes remain listed when they cannot connect.

status contains connection details. Changing backupEnabled requires a connected, backup-capable node. Deleting a node does not uninstall its software.

Import returns a new ID and status 201 per node. Edits, moves and deletions return 204 per node.

Probe, sync and reduce

Single-node calls have no body. Batches select nodes with nodeIds, groupIds, or both in the URL query or JSON body. The action options are:

Use true or false for boolean parameters.

PUT /api/v1/nodes/node-id/doProbe?refresh=false&wait=true
Authorization: Bearer <accessToken>

Probe returns 204; for Agents and older Servers this means started, even with wait=true.

Sync and reduce return 200 with a text result. Check that text for errors, even when the HTTP status is 200. With wait=false, check node status for the outcome.

Backups

Create and restore require a connected, backup-capable node: Server 16.7+ or Agent 2.15+. Stored backups can be listed, downloaded and deleted offline. Creation uses backups.credentials from Manager settings and applies the configured retention policy.

Use the exact listed filename, URL-encoded, for download or deletion:

{"backups":[{"filename":"node_id.ot-base","timestamp":"2026-09-25 10:00:00","size":"0.01 MB"}]}

For a single restore, send raw backup bytes with Content-Type: application/octet-stream or JSON selecting a stored file: {"filename":"node_backup.ot-base"}. Check node status after 202; a restart may be needed.

Batch restore accepts JSON with a stored filename for each node:

{"nodeIds":["node-a","node-b"],"nodeOptions":{"node-a":{"filename":"server.ot-base"},"node-b":{"filename":"agent.ot-base"}}}

To upload files, send multipart form data with a manifest JSON field. In nodeOptions, use {"backup":"serverFile"} to reference the file part named serverFile. Stored filenames and uploaded files can be mixed in one request. Several nodes can reference the same uploaded file.

Each selected node needs a backup in nodeOptions. HTTP 202 means at least one restore started; check node status for the outcome.

Creation returns the existing backup result; batches include it per node:

{"backup":{"results":{"node-id":"Success"},"successCount":1,"errors":[]}}

Failed backup attempts appear in the per-node results.

Software updates

Read capabilities first. Use the returned product, selectionKey, file types and options. Server updates require version 13.4+.

For one node, send multipart form data with an installer file and optional settings JSON text field:

curl.exe -X POST `
  'https://manager.example/api/v1/nodes/node-id/softwareUpdates' `
  -H "Authorization: Bearer $token" `
  -F 'installer=@OTbase Network Discovery Installer V17.5.exe' `
  -F 'settings={};type=application/json'

For a batch, send a manifest JSON text field and a file part per installer ID:

{
  "nodeIds":["windows-node","linux-node","agent-node"],
  "installers":[
    {"id":"win","product":"Discovery Server","selectionKey":"windows"},
    {"id":"linux","product":"Discovery Server","selectionKey":"debian;amd64"},
    {"id":"agent","product":"Discovery Agent","selectionKey":"windows"}
  ],
  "nodeOptions":{"linux-node":{"installer":"linux","settings":{}}}
}

curl.exe -X POST `
  'https://manager.example/api/v1/batch/nodes/softwareUpdates' `
  -H "Authorization: Bearer $token" `
  -F 'manifest=<manifest.json;type=application/json' `
  -F 'win=@OTbase Network Discovery Installer V17.5.exe' `
  -F 'linux=@discovery-service-amd64.deb' `
  -F 'agent=@OTbase Discovery Agent Installer V2.16.exe'

Each node must match one installer by product and selectionKey. Use nodeOptions to choose an installer and settings for individual nodes.

202 returns a softwareUpdate with an ID. Batches return one per accepted node. Poll each ID:

Deleting a starting update requests cancellation. Deleting an accepted or finished update removes its status record; it does not undo installation.

Software uninstall

Requires a connected Server or Agent with remote updates enabled. Docker is unsupported. 202 means accepted; check node status for the outcome.

Local accounts

Both forms take JSON. Batches select nodeIds and groupIds in the URL or body; omitting both selects all configured nodes. Use the JSON login fields for node authentication.

Login attempts use session credentials, then oldPasswords, then credentials.

These are local accounts; LDAP accounts are excluded. Changes require remote configuration. A node that does not expose the required account operations returns 422.

Add users or change passwords

{
  "nodeIds":["node-a","node-b"],
  "oldPasswords":["previous-password"],
  "credentials":[{"user":"bootstrap-admin","password":"bootstrap-password"}],
  "users":[{"user":"operator","password":"new-password"}],
  "addUser":true
}

All fields are optional. users defaults to the session account. addUser=true creates missing local admins; otherwise missing users return not_found.

oldPasswords helps authenticate with a previous password; it does not change the Manager password. Check each user's result.

List or remove users

doGetCredentials accepts {} plus the optional login fields. It returns the primary user first, then additional admins, without passwords or hashes:

{"nodeId":"node-a","status":200,"users":[{"user":"admin","primary":true},{"user":"operator","primary":false}]}

doRemoveCredentials requires a nonempty username list: {"users":["operator"]}. The primary user cannot be removed. Check each user's result.

doRemoveAllCredentials removes all additional admins and preserves the primary account. It accepts optional login fields and batch selection, but no users or addUser.

Batch responses contain one result per node.

Diagnostics

Requires Server 17.0+ or Agent 2.15+. Select files with an optional JSON body:

{"include":["logs","diagnostics","export"]}

Defaults are diagnostics for Servers and config plus logs for Agents. Other choices depend on node support. Poll until the job is ready or failed; ready includes downloadUrl. Check warnings for missing components.

For a batch, put nodeIds, groupIds, or both in the URL or the same body:

{"nodeIds":["node-a","node-b"],"include":["logs"]}

Omit both selectors to include all configured nodes. Each result contains the node's job or an error. Poll and download accepted jobs using the paths above.

History and settings

Audit event types: backup, blocked, connection, diagnostics, group, login, node, security, session, settings.

Settings use the UI's nested field names:

{"reconnectEnabled":true,"backups":{"enabled":true,"startAt":"03:00"}}

Settings changes require an exclusive Manager session. name and proxy.tempPath are read-only. Passwords and private keys are write-only.

settings.admins contains additional Manager administrators, not local accounts from Discovery Server or Discovery Agent.

Lists such as admins, backups.credentials and LDAP settings are replaced as a whole. An existing username without a new password keeps its password:

{"admins":[{"user":"existing-admin"},{"user":"new-admin","password":"new-password"}]}

Errors

Errors contain error and message, sometimes nodeId. Account operations can also include partial per-user results.

{"error":"node_not_found","message":"The requested node was not found."}

Common HTTP status codes are:

Other failures can report 5xx status codes. Read the response body for the specific cause.