Skip to content

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 the client_api_enabled custom parameter with a value true to an Agent Profile.

mceclip0.png

Agent binds to 127.0.0.1 interface to listen to API calls.

Note

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

Sample response

    { "token": "WV44TS4MZCAUXLBJ2MRX6MVCW4" }

Get Status

Allows to see current status of the client.

GET /api/v3/client?token=xxx

Sample response

{  
    "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"  
    }  
}
Field Description
state Possible values:
  • 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

Note

Available in Resilio Active Everywhere 3.0 and newer.

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

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

Sample response

[  
    {  
    "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  
    }  
]
Field Description
type Possible values:
  • folder - Synchronization job
  • transfer - Distribution, Consolidation job
  • script - Script job
status Possible values, applicable to all Job types:
  • error
  • loading
  • paused
  • writing acl
  • processing files
  • indexing
  • low priority
Values applicable to Synchronization Jobs:
  • mounting selective sync volume
  • no peers
  • syncing
  • synced
Values applicable to Distribution and 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
Values applicable to 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

Applicable parameters

Parameter Description
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

Note

Available in Resilio Active Everywhere 4.1 and newer.

 

PATCH /api/v3/client

Body:

    {"restart": true}

Set tag

Note

Available in Resilio Active Everywhere 2.9.3 and newer.

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"  
        }  
      ]  
    }

Sample response

{}

Get tags

Note

Available in Resilio Active Everywhere 2.10.0 and newer.

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"
        }
      ]
    }