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:

{
 "paused": false,
 "server": 
 {
  "addr": "127.0.0.1:8444",
  "state": "CONNECTED"
 }
}

 

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/{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
  }
]

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. 

No response provided. Check the HTTP code to verify if the call was successful.

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