Articles in this section

Using Agent API

Agent API can be used to control client behavior locally without the need for UI. It is supported only for desktop Agents. 

Enabling and configuring agent API

To enable Agent API for an agent, add a new custom parameter client_api_enabled with a value true to an Agent Profile.mceclip0.png

Agent binds to 127.0.0.1 interface to listen to API calls. It is not possible to bind it to a different interface.

Agent API receives requests over 3840 port by default, but it can use a different port. Specify the desired port as a value of a client_api_port custom parameter.

By default, a token is included in all API calls to protect against cross-site request forgery. Add custom parameter client_api_token_auth with a value false to disable the need for token when accessing API.

API calls

Get Token

Get security token. Use token in subsequent API calls to prevent cross-site scripting attack.

GET http://localhost:3840/api/v3/token

Response sample:

{ "token": "WV44TS4MZCAUXLBJ2MRX6MVCW4" }

Get Status

Allows to see current status of the client.

GET /api/v3/client?token=xxx

Response sample:

{
"deviceid": "EA...JA",
"deviceidHex": "201...20",
"name": "AgentName",
"paused": false,
"restartRequired":"true", //from v4.1.0. Missing, if restart of the Agent is not required.
"server": {
"addr": "management_console.com",
"last_seen": <unix_timestamp>,
"state": "CONNECTED"
}
}
"state" Possible states:
NOT_CONFIGURED - connection to MC is not yet configured for this Agent. It's not connected to any MC.
NOT_CONNECTED - Agent is not connected to the configured MC.
CONNECTING - Agent is establishing connection to the configured MC.
CONNECTED - Agent is connected to the configured MC.
PENDING_APPROVAL - Agent is connected to the configured MC, awaiting for being approved or declined. 
DECLINED - Agent's connection to MC was declined.
STOPPED - Network is not available on Agent's host.
WAITING_FOR_INCOMING_CONNECTION - Available for Proxy Server mode

Get status of jobs (starting from 3.0.0)

Reports status for job runs or a specific job run. Fields are self-descriptive. 

GET /api/v3/runs
GET /api/v3/runs/{run_id}

Response sample

[
  {
    "down_speed": 177840,
    "errors": [],
    "eta": 101,
    "files_completed": 208,
    "files_total": 209,
    "id": 384,
    "name": "FullSync",
    "path": "C:\\UserData\\FullSync",
    "peers_count": 1,
    "peers_count_proxied": 0,
    "permission": "rw",
    "run_id": 543,
    "size_completed": 126936039,
    "size_total": 144943317,
    "status": "syncing",
    "transferred_down": 107847067,
    "transferred_up": 0,
    "type": "folder",
    "up_speed": 0,
    "last_synced": 1702985796
  }
]
"type" "folder" - Synchronization job
"transfer" - Distribution, Consolidation job
"script" - Script job
"status" Possible statuses: 
general statuses for all types of jobs: error, loading, paused, writing acl, processing files, indexing, low priority
for Synchronisation jobs: mounting selective sync volume no peers syncing synced
for Distribution or Consolidation jobs: invalid state, no peers, waiting for files from source, downloading, seeding, cleaning up destination folder, waiting for scheduled script, executing pre-indexing script, executing post-download script, executing complete script, archiving script logs, successfully finished, expired
for Script jobs: expired, successfully finished, executing script
"last_synced" Unix timestamp for the last of time agent switched from non-zero data difference to zero data difference (which usually indicates that agent finished syncing)

Pause / Resume

Allows to pause/resume agent instantly or set resume timer to automatically resume after some time. The pause here stops all agent activities, including network activity, like file tree merge and service information exchange between agents. While agent is paused, it reports to the Management Console ‘paused’ state for every transfer.

PATCH /api/v3/client?token=xxx&paused=true&resume_timer=60

Parameters:

paused can be true or false to pause and unpause agent respectively
resume_timer

optional, a time interval after which agent unpauses, takes value in seconds

If resume_timer is omitted, agent will remain paused until restarted or unpaused over another call with paused=false. Whenever agent gets restarted or unpaused, resume_timer is reset. 

Restart the Agent (from 4.1.0)

PATCH /api/v3/client

Body:

{'restart': true}

Set tag (starting from 2.9.3)

Assigns a tag with value to the Agent. Creates new tag if it does not exist or updates existing one if tag already exists. Allows agent to migrate between groups with automatic sorting rules, as well as pause-unpause jobs using the "Pause job if" parameter in job profile (only available starting from 2.9.3).

PATCH /api/v3/tags?token=xxx

Body:

{
  "tags": [
    {
      "name":"TAG_NAME",
      "value":"TAG_VALUE"
    }
  ]
}

Response sample:

{}

Get tags (starting from 2.10.0)

Lists all tags and their values for an agent.

GET /api/v3/tags?token=xxx

Response sample:

{
  "tags": [
    {
      "name": "NAME1",
      "value": "VALUE1"
    },
    {
      "name": "NAME2",
      "value": "VALUE2"
    }
  ]
}

Related articles