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