1041 lines
26 KiB
Groff
1041 lines
26 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SYNCTHING-REST-API" "7" "December 11, 2016" "v0.14" "Syncthing"
|
|
.SH NAME
|
|
syncthing-rest-api \- REST API
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH DESCRIPTION
|
|
.sp
|
|
Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
|
|
the GUI code (JavaScript) and can be used by other processes wishing to control
|
|
Syncthing. In most cases both the input and output data is in JSON format. The
|
|
interface is subject to change.
|
|
.SH API KEY
|
|
.sp
|
|
To use the REST AP an API key must be set and used. The API key can be
|
|
generated in the GUI, or set in the \fBconfiguration/gui/apikey\fP element in
|
|
the configuration file. To use an API key, set the request header
|
|
\fBX\-API\-Key\fP to the API key value. For example, \fBcurl \-X POST \-H
|
|
"X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be used to invoke
|
|
with \fBcurl\fP\&.
|
|
.SH SYSTEM ENDPOINTS
|
|
.SS GET /rest/system/config
|
|
.sp
|
|
Returns the current configuration.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
{
|
|
"version": 15,
|
|
"folders": [
|
|
{
|
|
"id": "GXWxf\-3zgnU",
|
|
"label": "MyFolder",
|
|
"path": "...",
|
|
"type": "readwrite",
|
|
"devices": [
|
|
{
|
|
"deviceID": "..."
|
|
}
|
|
],
|
|
"rescanIntervalS": 60,
|
|
"ignorePerms": false,
|
|
"autoNormalize": true,
|
|
"minDiskFreePct": 1,
|
|
"versioning": {
|
|
"type": "",
|
|
"params": {}
|
|
},
|
|
"copiers": 0,
|
|
"pullers": 0,
|
|
"hashers": 0,
|
|
"order": "random",
|
|
"ignoreDelete": false,
|
|
"scanProgressIntervalS": 0,
|
|
"pullerSleepS": 0,
|
|
"pullerPauseS": 0,
|
|
"maxConflicts": 10,
|
|
"disableSparseFiles": false,
|
|
"disableTempIndexes": false,
|
|
"fsync": false,
|
|
"invalid": ""
|
|
}
|
|
],
|
|
"devices": [
|
|
{
|
|
"deviceID": "...",
|
|
"name": "Laptop",
|
|
"addresses": [
|
|
"dynamic",
|
|
"tcp://192.168.1.2:22000"
|
|
],
|
|
"compression": "metadata",
|
|
"certName": "",
|
|
"introducer": false
|
|
}
|
|
],
|
|
"gui": {
|
|
"enabled": true,
|
|
"address": "127.0.0.1:8384",
|
|
"user": "Username",
|
|
"password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
|
|
"useTLS": false,
|
|
"apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr",
|
|
"insecureAdminAccess": false,
|
|
"theme": "default"
|
|
},
|
|
"options": {
|
|
"listenAddresses": [
|
|
"default"
|
|
],
|
|
"globalAnnounceServers": [
|
|
"default"
|
|
],
|
|
"globalAnnounceEnabled": true,
|
|
"localAnnounceEnabled": true,
|
|
"localAnnouncePort": 21027,
|
|
"localAnnounceMCAddr": "[ff12::8384]:21027",
|
|
"maxSendKbps": 0,
|
|
"maxRecvKbps": 0,
|
|
"reconnectionIntervalS": 60,
|
|
"relaysEnabled": true,
|
|
"relayReconnectIntervalM": 10,
|
|
"startBrowser": false,
|
|
"natEnabled": true,
|
|
"natLeaseMinutes": 60,
|
|
"natRenewalMinutes": 30,
|
|
"natTimeoutSeconds": 10,
|
|
"urAccepted": \-1,
|
|
"urUniqueId": "",
|
|
"urURL": "https://data.syncthing.net/newdata",
|
|
"urPostInsecurely": false,
|
|
"urInitialDelayS": 1800,
|
|
"restartOnWakeup": true,
|
|
"autoUpgradeIntervalH": 12,
|
|
"keepTemporariesH": 24,
|
|
"cacheIgnoredFiles": false,
|
|
"progressUpdateIntervalS": 5,
|
|
"symlinksEnabled": true,
|
|
"limitBandwidthInLan": false,
|
|
"minHomeDiskFreePct": 1,
|
|
"releasesURL": "https://upgrades.syncthing.net/meta.json",
|
|
"alwaysLocalNets": [],
|
|
"overwriteRemoteDeviceNamesOnConnect": false,
|
|
"tempIndexMinBlocks": 10
|
|
},
|
|
"ignoredDevices": []
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/system/config/insync
|
|
.sp
|
|
Returns whether the config is in sync, i.e. whether the running
|
|
configuration is the same as that on disk.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"configInSync": true
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/config
|
|
.sp
|
|
Post the full contents of the configuration, in the same format as returned by
|
|
the corresponding GET request. The configuration will be saved to disk and the
|
|
\fBconfigInSync\fP flag set to false. Restart Syncthing to activate.
|
|
.SS GET /rest/system/connections
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Return format changed in 0.13.0.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Returns the list of configured devices and some metadata associated
|
|
with them. The list also contains the local device itself as not connected.
|
|
.sp
|
|
The connection types are \fBTCP (Client)\fP, \fBTCP (Server)\fP, \fBRelay (Client)\fP and \fBRelay (Server)\fP\&.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"total" : {
|
|
"paused" : false,
|
|
"clientVersion" : "",
|
|
"at" : "2015\-11\-07T17:29:47.691637262+01:00",
|
|
"connected" : false,
|
|
"inBytesTotal" : 1479,
|
|
"type" : "",
|
|
"outBytesTotal" : 1318,
|
|
"address" : ""
|
|
},
|
|
"connections" : {
|
|
"YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC" : {
|
|
"connected" : true,
|
|
"inBytesTotal" : 556,
|
|
"paused" : false,
|
|
"at" : "2015\-11\-07T17:29:47.691548971+01:00",
|
|
"clientVersion" : "v0.12.1",
|
|
"address" : "127.0.0.1:22002",
|
|
"type" : "TCP (Client)",
|
|
"outBytesTotal" : 550
|
|
},
|
|
"DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA" : {
|
|
"outBytesTotal" : 0,
|
|
"type" : "",
|
|
"address" : "",
|
|
"at" : "0001\-01\-01T00:00:00Z",
|
|
"clientVersion" : "",
|
|
"paused" : false,
|
|
"inBytesTotal" : 0,
|
|
"connected" : false
|
|
},
|
|
"UYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4" : {
|
|
"address" : "",
|
|
"type" : "",
|
|
"outBytesTotal" : 0,
|
|
"connected" : false,
|
|
"inBytesTotal" : 0,
|
|
"paused" : false,
|
|
"at" : "0001\-01\-01T00:00:00Z",
|
|
"clientVersion" : ""
|
|
}
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/system/debug
|
|
.sp
|
|
New in version 0.12.0.
|
|
|
|
.sp
|
|
Returns the set of debug facilities and which of them are currently enabled.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"enabled": [
|
|
"beacon"
|
|
],
|
|
"facilities": {
|
|
"beacon": "Multicast and broadcast discovery",
|
|
"config": "Configuration loading and saving",
|
|
"connections": "Connection handling",
|
|
"db": "The database layer",
|
|
"dialer": "Dialing connections",
|
|
"discover": "Remote device discovery",
|
|
"events": "Event generation and logging",
|
|
"http": "REST API",
|
|
"main": "Main package",
|
|
"model": "The root hub",
|
|
"protocol": "The BEP protocol",
|
|
"relay": "Relay connection handling",
|
|
"scanner": "File change detection and hashing",
|
|
"stats": "Persistent device and folder statistics",
|
|
"sync": "Mutexes",
|
|
"upgrade": "Binary upgrades",
|
|
"upnp": "UPnP discovery and port mapping",
|
|
"versioner": "File versioning"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/debug
|
|
.sp
|
|
New in version 0.12.0.
|
|
|
|
.sp
|
|
Enables or disables debugging for specified facilities. Give one or both of
|
|
\fBenable\fP and \fBdisable\fP query parameters, with comma separated facility
|
|
names. To disable debugging of the beacon and discovery packages, and enable it
|
|
for config and db:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-H X\-API\-Key:abc123 \-X POST \(aqhttp://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db\(aq
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/system/discovery
|
|
.sp
|
|
Returns the contents of the local discovery cache.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
|
|
"192.162.129.11:22000"
|
|
]
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/discovery
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Removed in v0.12.0.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Post with the query parameters \fBdevice\fP and \fBaddr\fP to add entries to
|
|
the discovery cache.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
curl \-X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
|
|
# Or with the X\-API\-Key header:
|
|
curl \-X POST \-\-header "X\-API\-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ" http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/error/clear
|
|
.sp
|
|
Post with empty to body to remove all recent errors.
|
|
.SS GET /rest/system/error
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Return format changed in 0.12.0.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Returns the list of recent errors.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"errors": [
|
|
{
|
|
"when": "2014\-09\-18T12:59:26.549953186+02:00",
|
|
"message": "This is an error string"
|
|
}
|
|
]
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/error
|
|
.sp
|
|
Post with an error message in the body (plain text) to register a new
|
|
error. The new error will be displayed on any active GUI clients.
|
|
.SS GET /rest/system/log
|
|
.sp
|
|
New in version 0.12.0.
|
|
|
|
.sp
|
|
Returns the list of recent log entries.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"messages": [
|
|
{
|
|
"when": "2014\-09\-18T12:59:26.549953186+02:00",
|
|
"message": "This is a log entry"
|
|
}
|
|
]
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/pause
|
|
.sp
|
|
Pause the given device.
|
|
.sp
|
|
Takes the mandatory \fBdevice\fP parameter and returns status 200 and no content upon success, or status 500 and a plain text error on failure.
|
|
.SS GET /rest/system/ping
|
|
.sp
|
|
Returns a \fB{"ping": "pong"}\fP object.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"ping": "pong"
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/ping
|
|
.sp
|
|
Returns a \fB{"ping": "pong"}\fP object.
|
|
.SS POST /rest/system/reset
|
|
.sp
|
|
Post with empty body to erase the current index database and restart
|
|
Syncthing. With no query parameters, the entire database is erased from disk.
|
|
By specifying the \fBfolder\fP parameter with a valid folder ID, only
|
|
information for that folder will be erased:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/restart
|
|
.sp
|
|
Post with empty body to immediately restart Syncthing.
|
|
.SS POST /rest/system/resume
|
|
.sp
|
|
Resume the given device.
|
|
.sp
|
|
Takes the mandatory \fBdevice\fP parameter and returns status 200 and no content upon success, or status 500 and a plain text error on failure.
|
|
.SS POST /rest/system/shutdown
|
|
.sp
|
|
Post with empty body to cause Syncthing to exit and not restart.
|
|
.SS GET /rest/system/status
|
|
.sp
|
|
Returns information about current system status and resource usage.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"alloc": 30618136,
|
|
"connectionServiceStatus": {
|
|
"dynamic+https://relays.syncthing.net/endpoint": {
|
|
"lanAddresses": [
|
|
"relay://23.92.71.120:443/?id=53STGR7\-YBM6FCX\-PAZ2RHM\-YPY6OEJ\-WYHVZO7\-PCKQRCK\-PZLTP7T\-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7"
|
|
],
|
|
"wanAddresses": [
|
|
"relay://23.92.71.120:443/?id=53STGR7\-YBM6FCX\-PAZ2RHM\-YPY6OEJ\-WYHVZO7\-PCKQRCK\-PZLTP7T\-434XCAD&pingInterval=1m0s&networkTimeout=2m0s&sessionLimitBps=0&globalLimitBps=0&statusAddr=:22070&providedBy=canton7"
|
|
]
|
|
},
|
|
"tcp://0.0.0.0:22000": {
|
|
"lanAddresses": [
|
|
"tcp://0.0.0.0:22000"
|
|
],
|
|
"wanAddresses": [
|
|
"tcp://0.0.0.0:22000"
|
|
]
|
|
}
|
|
},
|
|
"cpuPercent": 0.006944836512046966,
|
|
"discoveryEnabled": true,
|
|
"discoveryErrors": {
|
|
"global@https://discovery\-v4\-1.syncthing.net/v2/": "500 Internal Server Error",
|
|
"global@https://discovery\-v4\-2.syncthing.net/v2/": "Post https://discovery\-v4\-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)",
|
|
"global@https://discovery\-v4\-3.syncthing.net/v2/": "Post https://discovery\-v4\-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)",
|
|
"global@https://discovery\-v6\-1.syncthing.net/v2/": "Post https://discovery\-v6\-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host",
|
|
"global@https://discovery\-v6\-2.syncthing.net/v2/": "Post https://discovery\-v6\-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host",
|
|
"global@https://discovery\-v6\-3.syncthing.net/v2/": "Post https://discovery\-v6\-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host"
|
|
},
|
|
"discoveryMethods": 8,
|
|
"goroutines": 49,
|
|
"myID": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2",
|
|
"pathSeparator": "/",
|
|
"startTime": "2016\-06\-06T19:41:43.039284753+02:00",
|
|
"sys": 42092792,
|
|
"themes": [
|
|
"default",
|
|
"dark"
|
|
],
|
|
"tilde": "/Users/jb",
|
|
"uptime": 2635
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/system/upgrade
|
|
.sp
|
|
Checks for a possible upgrade and returns an object describing the
|
|
newest version and upgrade possibility.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"latest": "v0.10.27",
|
|
"newer": false,
|
|
"running": "v0.10.27+5\-g36c93b7"
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/system/upgrade
|
|
.sp
|
|
Perform an upgrade to the newest released version and restart. Does
|
|
nothing if there is no newer version than currently running.
|
|
.SS GET /rest/system/version
|
|
.sp
|
|
Returns the current Syncthing version information.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"arch": "amd64",
|
|
"longVersion": "syncthing v0.10.27+3\-gea8c3de (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 11:01:29 UTC",
|
|
"os": "darwin",
|
|
"version": "v0.10.27+3\-gea8c3de"
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH DATABASE ENDPOINTS
|
|
.SS GET /rest/db/browse
|
|
.sp
|
|
Returns the directory tree of the global model. Directories are always
|
|
JSON objects (map/dictionary), and files are always arrays of
|
|
modification time and size. The first integer is the files modification
|
|
time, and the second integer is the file size.
|
|
.sp
|
|
The call takes one mandatory \fBfolder\fP parameter and two optional
|
|
parameters. Optional parameter \fBlevels\fP defines how deep within the
|
|
tree we want to dwell down (0 based, defaults to unlimited depth)
|
|
Optional parameter \fBprefix\fP defines a prefix within the tree where to
|
|
start building the structure.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-s http://localhost:8384/rest/db/browse?folder=default | json_pp
|
|
{
|
|
"directory": {
|
|
"file": ["2015\-04\-20T22:20:45+09:00", 130940928],
|
|
"subdirectory": {
|
|
"another file": ["2015\-04\-20T22:20:45+09:00", 130940928]
|
|
}
|
|
},
|
|
"rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
|
|
}
|
|
|
|
$ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
|
|
{
|
|
"directory": {},
|
|
"rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
|
|
}
|
|
|
|
$ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
|
|
{
|
|
"directory": {
|
|
"file": ["2015\-04\-20T22:20:45+09:00", 130940928],
|
|
"subdirectory": {}
|
|
},
|
|
"rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
|
|
}
|
|
|
|
$ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
|
|
{
|
|
"another file": ["2015\-04\-20T22:20:45+09:00", 130940928]
|
|
}
|
|
|
|
$ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
|
|
{
|
|
"file": ["2015\-04\-20T22:20:45+09:00", 130940928],
|
|
"subdirectory": {}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/db/completion
|
|
.sp
|
|
Returns the completion percentage (0 to 100) for a given device and
|
|
folder. Takes \fBdevice\fP and \fBfolder\fP parameters.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"completion": 0
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/db/file
|
|
.sp
|
|
Returns most data available about a given file, including version and
|
|
availability. Takes \fBfolder\fP and \fBfile\fP parameters.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"availability": [
|
|
"I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU"
|
|
],
|
|
"global": {
|
|
"flags": "0644",
|
|
"sequence": 3,
|
|
"modified": "2015\-04\-20T22:20:45+09:00",
|
|
"name": "util.go",
|
|
"numBlocks": 1,
|
|
"size": 9642,
|
|
"version": [
|
|
"5407294127585413568:1"
|
|
]
|
|
},
|
|
"local": {
|
|
"flags": "0644",
|
|
"sequence": 4,
|
|
"modified": "2015\-04\-20T22:20:45+09:00",
|
|
"name": "util.go",
|
|
"numBlocks": 1,
|
|
"size": 9642,
|
|
"version": [
|
|
"5407294127585413568:1"
|
|
]
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/db/ignores
|
|
.sp
|
|
Takes one parameter, \fBfolder\fP, and returns the content of the
|
|
\fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBexpanded\fP,
|
|
provides a list of strings which represent globbing patterns described by gobwas/glob (based on standard wildcards) that match the patterns in \fB\&.stignore\fP and all the includes. If appropriate these globs are prepended by the following modifiers: \fB!\fP to negate the glob, \fB(?i)\fP to do case insensitive matching and \fB(?d)\fP to enable removing of ignored files in an otherwise empty directory.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"ignore": [
|
|
"(?i)/Backups"
|
|
],
|
|
"expanded": [
|
|
"(?i)Backups",
|
|
"(?i)Backups/**"
|
|
]
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/db/ignores
|
|
.sp
|
|
Expects a format similar to the output of \fBGET\fP call, but only
|
|
containing the \fBignore\fP field (\fBexpanded\fP field should be omitted).
|
|
It takes one parameter, \fBfolder\fP, and either updates the content of
|
|
the \fB\&.stignore\fP echoing it back as a response, or returns an error.
|
|
.SS GET /rest/db/need
|
|
.sp
|
|
Takes one mandatory parameter, \fBfolder\fP, and returns lists of files which are
|
|
needed by this device in order for it to become in sync.
|
|
.sp
|
|
Furthermore takes an optional \fBpage\fP and \fBperpage\fP arguments for pagination.
|
|
Pagination happens, across the union of all needed files, that is \- across all
|
|
3 sections of the response.
|
|
For example, given the current need state is as follows:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
\fBprogress\fP has 15 items
|
|
.IP 2. 3
|
|
\fBqueued\fP has 3 items
|
|
.IP 3. 3
|
|
\fBrest\fP has 12 items
|
|
.UNINDENT
|
|
.sp
|
|
If you issue a query with \fBpage=1\fP and \fBperpage=10\fP, only the \fBprogress\fP
|
|
section in the response will have 10 items. If you issue a request query with
|
|
\fBpage=2\fP and \fBperpage=10\fP, \fBprogress\fP section will have the last 5 items,
|
|
\fBqueued\fP section will have all 3 items, and \fBrest\fP section will have first
|
|
2 items. If you issue a query for \fBpage=3\fP and \fBperpage=10\fP, you will only
|
|
have the last 10 items of the \fBrest\fP section.
|
|
.sp
|
|
In all these calls, \fBtotal\fP will be 30 to indicate the total number of
|
|
available items.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
# Files currently being downloaded
|
|
"progress": [
|
|
{
|
|
"flags": "0755",
|
|
"sequence": 6,
|
|
"modified": "2015\-04\-20T23:06:12+09:00",
|
|
"name": "ls",
|
|
"size": 34640,
|
|
"version": [
|
|
"5157751870738175669:1"
|
|
]
|
|
}
|
|
],
|
|
# Files queued to be downloaded next (as per array order)
|
|
"queued": [
|
|
...
|
|
],
|
|
# Files to be downloaded after all queued files will be downloaded.
|
|
# This happens when we start downloading files, and new files get added while we are downloading.
|
|
"rest": [
|
|
...
|
|
],
|
|
"page": 1,
|
|
"perpage": 100,
|
|
"total": 2000
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/db/override
|
|
.sp
|
|
Request override of a master folder.
|
|
Takes the mandatory parameter \fIfolder\fP (folder ID).
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
curl \-X POST http://127.0.0.1:8384/rest/db/override?folder=default
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS POST /rest/db/prio
|
|
.sp
|
|
Moves the file to the top of the download queue.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Response contains the same output as \fBGET /rest/db/need\fP
|
|
.SS POST /rest/db/scan
|
|
.sp
|
|
Request immediate rescan of a folder, or a specific path within a folder.
|
|
Takes the mandatory parameter \fIfolder\fP (folder ID), an optional parameter
|
|
\fBsub\fP (path relative to the folder root) and an optional parameter \fBnext\fP\&. If
|
|
\fBsub\fP is omitted or empty, the entire folder is scanned for changes, otherwise
|
|
only the given path (and children, in case it\(aqs a directory) is scanned. The
|
|
\fBnext\fP argument delays Syncthing\(aqs automated rescan interval for a given
|
|
amount of seconds.
|
|
.sp
|
|
Requesting scan of a path that no longer exists, but previously did, is
|
|
valid and will result in Syncthing noticing the deletion of the path in
|
|
question.
|
|
.sp
|
|
Returns status 200 and no content upon success, or status 500 and a
|
|
plain text error if an error occurred during scanning.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/db/status
|
|
.sp
|
|
Returns information about the current status of a folder.
|
|
.sp
|
|
Parameters: \fBfolder\fP, the ID of a folder.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
# latest version according to cluster:
|
|
"globalBytes": 13173473780,
|
|
"globalDeleted": 1847,
|
|
"globalFiles": 42106,
|
|
# what we have locally:
|
|
"localBytes": 13173473780,
|
|
"localDeleted": 1847,
|
|
"localFiles": 42106,
|
|
# which part of what we have locally is the latest cluster version:
|
|
"inSyncBytes": 13173473780,
|
|
"inSyncFiles": 42106,
|
|
# which part of what we have locally should be fetched from the cluster:
|
|
"needBytes": 0,
|
|
"needFiles": 0,
|
|
# various other metadata
|
|
"ignorePatterns": true,
|
|
"invalid": "",
|
|
"state": "idle",
|
|
"stateChanged": "2015\-03\-16T21:47:28.750853241+01:00",
|
|
"version": 71989
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH STATISTICS ENDPOINTS
|
|
.SS GET /rest/stats/device
|
|
.sp
|
|
Returns general statistics about devices. Currently, only contains the
|
|
time the device was last seen.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-s http://localhost:8384/rest/stats/device | json
|
|
{
|
|
"P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
|
|
"lastSeen" : "2015\-04\-18T11:21:31.3256277+01:00"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/stats/folder
|
|
.sp
|
|
Returns general statistics about folders. Currently contains the
|
|
last scan time and the last synced file.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-s http://localhost:8384/rest/stats/folder | json
|
|
{
|
|
"folderid" : {
|
|
"lastScan": "2016\-06\-02T13:28:01.288181412\-04:00",
|
|
"lastFile" : {
|
|
"filename" : "file/name",
|
|
"at" : "2015\-04\-16T22:04:18.3066971+01:00"
|
|
}
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH MISC SERVICES ENDPOINTS
|
|
.SS GET /rest/svc/deviceid
|
|
.sp
|
|
Verifies and formats a device ID. Accepts all currently valid formats
|
|
(52 or 56 characters with or without separators, upper or lower case,
|
|
with trivial substitutions). Takes one parameter, \fBid\fP, and returns
|
|
either a valid device ID in modern format, or an error.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json
|
|
{
|
|
"error": "device ID invalid: incorrect length"
|
|
}
|
|
|
|
$ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
|
|
{
|
|
"id": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2"
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/svc/lang
|
|
.sp
|
|
Returns a list of canonicalized localization codes, as picked up from
|
|
the \fBAccept\-Language\fP header sent by the browser.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
["sv_sv","sv","en_us","en"]
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/svc/random/string
|
|
.sp
|
|
Returns a strong random generated string (alphanumeric) of the specified length. Takes the \fBlength\fP parameter.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"random": "FdPaEaZQ56sXEKYNxpgF"
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS GET /rest/svc/report
|
|
.sp
|
|
Returns the data sent in the anonymous usage report.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"folderMaxMiB" : 0,
|
|
"platform" : "linux\-amd64",
|
|
"totMiB" : 0,
|
|
"longVersion" : "syncthing v0.12.2 \e"Beryllium Bedbug\e" (go1.4.3 linux\-amd64 default) unknown\-user@build2.syncthing.net 2015\-11\-09 13:23:26 UTC",
|
|
"upgradeAllowedManual" : true,
|
|
"totFiles" : 3,
|
|
"folderUses" : {
|
|
"ignorePerms" : 0,
|
|
"autoNormalize" : 0,
|
|
"readonly" : 0,
|
|
"ignoreDelete" : 0
|
|
},
|
|
"memoryUsageMiB" : 13,
|
|
"version" : "v0.12.2",
|
|
"sha256Perf" : 27.28,
|
|
"numFolders" : 2,
|
|
"memorySize" : 1992,
|
|
"announce" : {
|
|
"defaultServersIP" : 0,
|
|
"otherServers" : 0,
|
|
"globalEnabled" : false,
|
|
"defaultServersDNS" : 1,
|
|
"localEnabled" : false
|
|
},
|
|
"usesRateLimit" : false,
|
|
"numCPU" : 2,
|
|
"uniqueID" : "",
|
|
"urVersion" : 2,
|
|
"rescanIntvs" : [
|
|
60,
|
|
60
|
|
],
|
|
"numDevices" : 2,
|
|
"folderMaxFiles" : 3,
|
|
"relays" : {
|
|
"defaultServers" : 1,
|
|
"enabled" : true,
|
|
"otherServers" : 0
|
|
},
|
|
"deviceUses" : {
|
|
"compressMetadata" : 1,
|
|
"customCertName" : 0,
|
|
"staticAddr" : 1,
|
|
"compressAlways" : 0,
|
|
"compressNever" : 1,
|
|
"introducer" : 0,
|
|
"dynamicAddr" : 1
|
|
},
|
|
"upgradeAllowedAuto" : false
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
The Syncthing Authors
|
|
.SH COPYRIGHT
|
|
2015, The Syncthing Authors
|
|
.\" Generated by docutils manpage writer.
|
|
.
|