mirror of
https://github.com/syncthing/syncthing.git
synced 2024-11-16 10:28:49 -07:00
2058 lines
55 KiB
Groff
2058 lines
55 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.
|
||
.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
|
||
..
|
||
.TH "SYNCTHING-REST-API" "7" "Jun 12, 2023" "v1.23.5" "Syncthing"
|
||
.SH NAME
|
||
syncthing-rest-api \- REST API
|
||
.sp
|
||
Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
|
||
the GUI (from 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 API 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 (add \fB\-k\fP flag when using HTTPS with a Syncthing generated or self signed certificate).
|
||
.sp
|
||
One exception to this requirement is \fB/rest/noauth\fP, you do not need an API
|
||
key to use those endpoints. This way third\-party devices and services can do
|
||
simple calls that don’t expose sensitive information without having to expose
|
||
your API key.
|
||
.SH RESULT PAGINATION
|
||
.sp
|
||
Some \fIGET\fP endpoints take optional \fBpage\fP and \fBperpage\fP arguments for
|
||
pagination. No more than \fBperpage\fP (defaults to 65536 if not given) result
|
||
entries are returned in an array. To access further entries, passing the
|
||
\fBpage\fP parameter will advance in the results by that many pages. The actually
|
||
used parameters are always returned as attributes in the response object.
|
||
.SH SYSTEM ENDPOINTS
|
||
.SS GET /rest/system/browse
|
||
.sp
|
||
Returns a list of directories matching the path given by the optional parameter
|
||
\fBcurrent\fP\&. The path can use \fI\%patterns as described in Go’s filepath package\fP <\fBhttps://pkg.go.dev/path/filepath#Match\fP>\&. A ‘*’ will always be appended
|
||
to the given path (e.g. \fB/tmp/\fP matches all its subdirectories). If the option
|
||
\fBcurrent\fP is not given, filesystem root paths are returned.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse | json_pp
|
||
[
|
||
"/"
|
||
]
|
||
|
||
$ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp
|
||
[
|
||
"/var/backups/",
|
||
"/var/cache/",
|
||
"/var/lib/",
|
||
"/var/local/",
|
||
"/var/lock/",
|
||
"/var/log/",
|
||
"/var/mail/",
|
||
"/var/opt/",
|
||
"/var/run/",
|
||
"/var/spool/",
|
||
"/var/tmp/"
|
||
]
|
||
|
||
$ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp
|
||
[
|
||
"/var/local/",
|
||
"/var/lock/",
|
||
"/var/log/",
|
||
"/var/opt/",
|
||
"/var/spool/"
|
||
]
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS GET /rest/system/config (DEPRECATED)
|
||
.sp
|
||
Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use rest\-config
|
||
instead.
|
||
|
||
.sp
|
||
Returns the current configuration.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"version": 35,
|
||
"folders": [
|
||
{
|
||
"id": "default",
|
||
"label": "Default Folder",
|
||
"filesystemType": "basic",
|
||
"path": "...",
|
||
"type": "sendreceive",
|
||
"devices": [
|
||
{
|
||
"deviceID": "...",
|
||
"introducedBy": "",
|
||
"encryptionPassword": ""
|
||
}
|
||
],
|
||
"rescanIntervalS": 3600,
|
||
"fsWatcherEnabled": true,
|
||
"fsWatcherDelayS": 10,
|
||
"ignorePerms": false,
|
||
"autoNormalize": true,
|
||
"minDiskFree": {
|
||
"value": 1,
|
||
"unit": "%"
|
||
},
|
||
"versioning": {
|
||
"type": "",
|
||
"params": {},
|
||
"cleanupIntervalS": 3600,
|
||
"fsPath": "",
|
||
"fsType": "basic"
|
||
},
|
||
"copiers": 0,
|
||
"pullerMaxPendingKiB": 0,
|
||
"hashers": 0,
|
||
"order": "random",
|
||
"ignoreDelete": false,
|
||
"scanProgressIntervalS": 0,
|
||
"pullerPauseS": 0,
|
||
"maxConflicts": \-1,
|
||
"disableSparseFiles": false,
|
||
"disableTempIndexes": false,
|
||
"paused": false,
|
||
"weakHashThresholdPct": 25,
|
||
"markerName": ".stfolder",
|
||
"copyOwnershipFromParent": false,
|
||
"modTimeWindowS": 0,
|
||
"maxConcurrentWrites": 2,
|
||
"disableFsync": false,
|
||
"blockPullOrder": "standard",
|
||
"copyRangeMethod": "standard",
|
||
"caseSensitiveFS": false,
|
||
"junctionsAsDirs": true
|
||
}
|
||
],
|
||
"devices": [
|
||
{
|
||
"deviceID": "...",
|
||
"name": "Laptop",
|
||
"addresses": [
|
||
"dynamic",
|
||
"tcp://192.168.1.2:22000"
|
||
],
|
||
"compression": "metadata",
|
||
"certName": "",
|
||
"introducer": false,
|
||
"skipIntroductionRemovals": false,
|
||
"introducedBy": "",
|
||
"paused": false,
|
||
"allowedNetworks": [],
|
||
"autoAcceptFolders": false,
|
||
"maxSendKbps": 0,
|
||
"maxRecvKbps": 0,
|
||
"ignoredFolders": [
|
||
{
|
||
"time": "2022\-01\-09T19:09:52Z",
|
||
"id": "br63e\-wyhb7",
|
||
"label": "Foo"
|
||
}
|
||
],
|
||
"maxRequestKiB": 0,
|
||
"untrusted": false,
|
||
"remoteGUIPort": 0
|
||
}
|
||
],
|
||
"gui": {
|
||
"enabled": true,
|
||
"address": "127.0.0.1:8384",
|
||
"unixSocketPermissions": "",
|
||
"user": "Username",
|
||
"password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
|
||
"authMode": "static",
|
||
"useTLS": false,
|
||
"apiKey": "k1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1",
|
||
"insecureAdminAccess": false,
|
||
"theme": "default",
|
||
"debugging": false,
|
||
"insecureSkipHostcheck": false,
|
||
"insecureAllowFrameLoading": false
|
||
},
|
||
"ldap": {
|
||
"address": "",
|
||
"bindDN": "",
|
||
"transport": "plain",
|
||
"insecureSkipVerify": false,
|
||
"searchBaseDN": "",
|
||
"searchFilter": ""
|
||
},
|
||
"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": true,
|
||
"natEnabled": true,
|
||
"natLeaseMinutes": 60,
|
||
"natRenewalMinutes": 30,
|
||
"natTimeoutSeconds": 10,
|
||
"urAccepted": 0,
|
||
"urSeen": 0,
|
||
"urUniqueId": "...",
|
||
"urURL": "https://data.syncthing.net/newdata",
|
||
"urPostInsecurely": false,
|
||
"urInitialDelayS": 1800,
|
||
"restartOnWakeup": true,
|
||
"autoUpgradeIntervalH": 12,
|
||
"upgradeToPreReleases": false,
|
||
"keepTemporariesH": 24,
|
||
"cacheIgnoredFiles": false,
|
||
"progressUpdateIntervalS": 5,
|
||
"limitBandwidthInLan": false,
|
||
"minHomeDiskFree": {
|
||
"value": 1,
|
||
"unit": "%"
|
||
},
|
||
"releasesURL": "https://upgrades.syncthing.net/meta.json",
|
||
"alwaysLocalNets": [],
|
||
"overwriteRemoteDeviceNamesOnConnect": false,
|
||
"tempIndexMinBlocks": 10,
|
||
"unackedNotificationIDs": [
|
||
"authenticationUserAndPassword"
|
||
],
|
||
"trafficClass": 0,
|
||
"setLowPriority": true,
|
||
"maxFolderConcurrency": 0,
|
||
"crURL": "https://crash.syncthing.net/newcrash",
|
||
"crashReportingEnabled": true,
|
||
"stunKeepaliveStartS": 180,
|
||
"stunKeepaliveMinS": 20,
|
||
"stunServers": [
|
||
"default"
|
||
],
|
||
"databaseTuning": "auto",
|
||
"maxConcurrentIncomingRequestKiB": 0,
|
||
"announceLANAddresses": true,
|
||
"sendFullIndexOnUpgrade": false,
|
||
"featureFlags": [],
|
||
"connectionLimitEnough": 0,
|
||
"connectionLimitMax": 0,
|
||
"insecureAllowOldTLSVersions": false
|
||
},
|
||
"remoteIgnoredDevices": [
|
||
{
|
||
"time": "2022\-01\-09T20:02:01Z",
|
||
"deviceID": "...",
|
||
"name": "...",
|
||
"address": "192.168.0.20:22000"
|
||
}
|
||
],
|
||
"defaults": {
|
||
"folder": {
|
||
"id": "",
|
||
"label": "",
|
||
"filesystemType": "basic",
|
||
"path": "~",
|
||
"type": "sendreceive",
|
||
"devices": [
|
||
{
|
||
"deviceID": "...",
|
||
"introducedBy": "",
|
||
"encryptionPassword": ""
|
||
}
|
||
],
|
||
"rescanIntervalS": 3600,
|
||
"fsWatcherEnabled": true,
|
||
"fsWatcherDelayS": 10,
|
||
"ignorePerms": false,
|
||
"autoNormalize": true,
|
||
"minDiskFree": {
|
||
"value": 1,
|
||
"unit": "%"
|
||
},
|
||
"versioning": {
|
||
"type": "",
|
||
"params": {},
|
||
"cleanupIntervalS": 3600,
|
||
"fsPath": "",
|
||
"fsType": "basic"
|
||
},
|
||
"copiers": 0,
|
||
"pullerMaxPendingKiB": 0,
|
||
"hashers": 0,
|
||
"order": "random",
|
||
"ignoreDelete": false,
|
||
"scanProgressIntervalS": 0,
|
||
"pullerPauseS": 0,
|
||
"maxConflicts": 10,
|
||
"disableSparseFiles": false,
|
||
"disableTempIndexes": false,
|
||
"paused": false,
|
||
"weakHashThresholdPct": 25,
|
||
"markerName": ".stfolder",
|
||
"copyOwnershipFromParent": false,
|
||
"modTimeWindowS": 0,
|
||
"maxConcurrentWrites": 2,
|
||
"disableFsync": false,
|
||
"blockPullOrder": "standard",
|
||
"copyRangeMethod": "standard",
|
||
"caseSensitiveFS": false,
|
||
"junctionsAsDirs": false
|
||
},
|
||
"device": {
|
||
"deviceID": "",
|
||
"name": "",
|
||
"addresses": [
|
||
"dynamic"
|
||
],
|
||
"compression": "metadata",
|
||
"certName": "",
|
||
"introducer": false,
|
||
"skipIntroductionRemovals": false,
|
||
"introducedBy": "",
|
||
"paused": false,
|
||
"allowedNetworks": [],
|
||
"autoAcceptFolders": false,
|
||
"maxSendKbps": 0,
|
||
"maxRecvKbps": 0,
|
||
"ignoredFolders": [],
|
||
"maxRequestKiB": 0,
|
||
"untrusted": false,
|
||
"remoteGUIPort": 0
|
||
}
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS GET /rest/system/config/insync (DEPRECATED)
|
||
.sp
|
||
Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use
|
||
rest\-config\-insync instead.
|
||
|
||
.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 (DEPRECATED)
|
||
.sp
|
||
Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use config
|
||
instead.
|
||
|
||
.sp
|
||
Post the full contents of the configuration, in the same format as returned by
|
||
the corresponding GET request. When posting the configuration succeeds,
|
||
the posted configuration is immediately applied, except for changes that require a restart. Query
|
||
rest\-config\-insync to check if a restart is required.
|
||
.sp
|
||
This endpoint is the main point to control Syncthing, even if the change only
|
||
concerns a very small part of the config: The usual workflow is to get the
|
||
config, modify the needed parts and post it again.
|
||
.SS GET /rest/system/connections
|
||
.sp
|
||
\fBNOTE:\fP
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
Return format changed in versions 0.13.0, 1.19.0 and 1.23.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
|
||
{
|
||
"connections": {
|
||
"DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA": {
|
||
"address": "",
|
||
"at": "0001\-01\-01T00:00:00Z",
|
||
"clientVersion": "",
|
||
"connected": false,
|
||
"inBytesTotal": 0,
|
||
"isLocal": false,
|
||
"outBytesTotal": 0,
|
||
"paused": false,
|
||
"startedAt": "0001\-01\-01T00:00:00Z",
|
||
"type": ""
|
||
},
|
||
"UYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4": {
|
||
"address": "",
|
||
"at": "0001\-01\-01T00:00:00Z",
|
||
"clientVersion": "",
|
||
"connected": false,
|
||
"inBytesTotal": 0,
|
||
"isLocal": false,
|
||
"outBytesTotal": 0,
|
||
"paused": false,
|
||
"startedAt": "0001\-01\-01T00:00:00Z",
|
||
"type": ""
|
||
},
|
||
"YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC": {
|
||
"address": "127.0.0.1:22002",
|
||
"at": "2015\-11\-07T17:29:47.691548971+01:00",
|
||
"clientVersion": "v0.12.1",
|
||
"connected": true,
|
||
"inBytesTotal": 556,
|
||
"isLocal": true,
|
||
"outBytesTotal": 550,
|
||
"paused": false,
|
||
"startedAt": "2015\-11\-07T00:09:47Z",
|
||
"type": "TCP (Client)"
|
||
}
|
||
},
|
||
"total": {
|
||
"at": "2015\-11\-07T17:29:47.691637262+01:00",
|
||
"inBytesTotal": 1479,
|
||
"outBytesTotal": 1318
|
||
}
|
||
}
|
||
.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. The optional \fBsince\fP parameter limits
|
||
the results to message newer than the given timestamp in \fI\%RFC 3339\fP <\fBhttps://datatracker.ietf.org/doc/html/rfc3339.html\fP> format.
|
||
.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 GET /rest/system/log.txt
|
||
.sp
|
||
Returns the same information, formatted as a text log instead of a JSON object.
|
||
.SS GET /rest/system/paths
|
||
.sp
|
||
New in version 1.21.0.
|
||
|
||
.sp
|
||
Returns the path locations used internally for storing configuration, database,
|
||
and others.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"auditLog": "/home/user/.local/share/syncthing/audit\-${timestamp}.log",
|
||
"baseDir\-config": "/home/user/.config/syncthing",
|
||
"baseDir\-data": "/home/user/.local/share/syncthing",
|
||
"baseDir\-userHome": "/home/user",
|
||
"certFile": "/home/user/.config/syncthing/cert.pem",
|
||
"config": "/home/user/.config/syncthing/config.xml",
|
||
"csrfTokens": "/home/user/.config/syncthing/csrftokens.txt",
|
||
"database": "/home/user/.local/share/syncthing/index\-v0.14.0.db",
|
||
"defFolder": "/home/user/Sync",
|
||
"guiAssets": "/home/user/src/syncthing/gui",
|
||
"httpsCertFile": "/home/user/.config/syncthing/https\-cert.pem",
|
||
"httpsKeyFile": "/home/user/.config/syncthing/https\-key.pem",
|
||
"keyFile": "/home/user/.config/syncthing/key.pem",
|
||
"logFile": "\-",
|
||
"panicLog": "/home/user/.local/share/syncthing/panic\-${timestamp}.log"
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS POST /rest/system/pause
|
||
.sp
|
||
Pause the given device or all devices.
|
||
.sp
|
||
Takes the optional parameter \fBdevice\fP (device ID). When omitted,
|
||
pauses all devices. 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=ab1c2\-def3g
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
\fBCaution\fP: See \fB\-\-reset\-database\fP for \fB\&.stfolder\fP creation
|
||
side\-effect and caution regarding mountpoints.
|
||
.SS POST /rest/system/restart
|
||
.sp
|
||
Post with empty body to immediately restart Syncthing.
|
||
.SS POST /rest/system/resume
|
||
.sp
|
||
Resume the given device or all devices.
|
||
.sp
|
||
Takes the optional parameter \fBdevice\fP (device ID). When omitted,
|
||
resumes all devices. 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. The CPU percent value has been deprecated from the API and will always report 0.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"alloc": 30618136,
|
||
"connectionServiceStatus": {
|
||
"dynamic+https://relays.syncthing.net/endpoint": {
|
||
"error": null,
|
||
"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": {
|
||
"error": null,
|
||
"lanAddresses": [
|
||
"tcp://0.0.0.0:22000"
|
||
],
|
||
"wanAddresses": [
|
||
"tcp://0.0.0.0:22000"
|
||
]
|
||
}
|
||
},
|
||
"cpuPercent": 0,
|
||
"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"
|
||
},
|
||
"discoveryStatus": {
|
||
"IPv4 local": {
|
||
"error": null
|
||
},
|
||
"IPv6 local": {
|
||
"error": null
|
||
},
|
||
"global@https://discovery\-v4\-1.syncthing.net/v2/": {
|
||
"error": "500 Internal Server Error"
|
||
},
|
||
"global@https://discovery\-v4\-2.syncthing.net/v2/": {
|
||
"error": "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/": {
|
||
"error": "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/": {
|
||
"error": "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/": {
|
||
"error": "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/": {
|
||
"error": "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,
|
||
"lastDialStatus": {
|
||
"tcp://10.20.30.40": {
|
||
"when": "2019\-05\-16T07:41:23Z",
|
||
"error": "dial tcp 10.20.30.40:22000: i/o timeout"
|
||
},
|
||
"tcp://172.16.33.3:22000": {
|
||
"when": "2019\-05\-16T07:40:43Z",
|
||
"ok": true
|
||
},
|
||
"tcp://83.233.120.221:22000": {
|
||
"when": "2019\-05\-16T07:41:13Z",
|
||
"error": "dial tcp 83.233.120.221:22000: connect: connection refused"
|
||
}
|
||
},
|
||
"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
|
||
.sp
|
||
New in version 1.2.0: The \fBlastDialStatus\fP dictionary contains the last error (or \fBnull\fP for
|
||
success) for each peer address that Syncthing has attempted to contact.
|
||
The \fBconnectionServiceStatus\fP entries gained \fB"error": null\fP
|
||
attributes where previously there would be no \fBerror\fP attribute at all
|
||
in the success case.
|
||
|
||
.sp
|
||
New in version 1.18.0: The \fBdiscoveryStatus\fP dictionary lists all configured discovery methods, not
|
||
only failed ones like the now deprecated \fBdiscoveryErrors\fP\&. Each entry is
|
||
an object itself (for consistency with other fields), where a \fBnull\fP value
|
||
for the \fBerror\fP attribute means the method is running successfully. This
|
||
effectively deprecates the \fBdiscoveryMethods\fP attribute as well, which now
|
||
always matches the number of entries in \fBdiscoveryStatus\fP\&.
|
||
|
||
.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.14.47",
|
||
"majorNewer": false,
|
||
"newer": true,
|
||
"running": "v0.14.46"
|
||
}
|
||
.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 CONFIG ENDPOINTS
|
||
.SS Config Endpoints
|
||
.sp
|
||
New in version 1.12.0.
|
||
|
||
.sp
|
||
These endpoints facilitate access and modification of the configuration in a granular way. Config sent to the endpoints must be in the
|
||
same format as returned by the corresponding GET request. When posting the
|
||
configuration succeeds, the posted configuration is immediately applied, except
|
||
for changes that require a restart. Query \fI\%/rest/config/restart\-required\fP to check if
|
||
a restart is required.
|
||
.sp
|
||
For all endpoints supporting \fBPATCH\fP, it takes the existing config and
|
||
unmarshals the given JSON object on top of it. This means all child objects will
|
||
replace the existing objects, not extend them. For example for
|
||
\fBRawListenAddresses\fP in options, which is an array of strings, sending
|
||
\fB{RawListenAddresses: ["tcp://10.0.0.2"]}\fP will replace all existing listen
|
||
addresses.
|
||
.SS /rest/config
|
||
.sp
|
||
\fBGET\fP returns the entire config and \fBPUT\fP replaces it.
|
||
.SS /rest/config/restart\-required
|
||
.sp
|
||
\fBGET\fP returns whether a restart of Syncthing is required for the current
|
||
config to take effect.
|
||
.SS /rest/config/folders, /rest/config/devices
|
||
.sp
|
||
\fBGET\fP returns all folders respectively devices as an array. \fBPUT\fP takes an array and
|
||
\fBPOST\fP a single object. In both cases if a given folder/device already exists,
|
||
it’s replaced, otherwise a new one is added.
|
||
.SS /rest/config/folders/*id*, /rest/config/devices/*id*
|
||
.sp
|
||
Put the desired folder\- respectively device\-ID in place of *id*. \fBGET\fP
|
||
returns the folder/device for the given ID, \fBPUT\fP replaces the entire config,
|
||
\fBPATCH\fP replaces only the given child objects and \fBDELETE\fP removes the
|
||
folder/device.
|
||
.SS /rest/config/defaults/folder, /rest/config/defaults/device
|
||
.sp
|
||
\fBGET\fP returns a template folder / device configuration object with all default
|
||
values, which only needs a unique ID to be applied. \fBPUT\fP replaces the
|
||
default config (omitted values are reset to the hard\-coded defaults), \fBPATCH\fP
|
||
replaces only the given child objects.
|
||
.SS /rest/config/defaults/ignores
|
||
.sp
|
||
New in version 1.19.0.
|
||
|
||
.sp
|
||
\fBGET\fP returns an object with a single \fBlines\fP attribute listing ignore
|
||
patterns to be used by default on folders, as an array of single\-line strings.
|
||
\fBPUT\fP replaces the default ignore patterns from an object of the same format.
|
||
.SS /rest/config/options, /rest/config/ldap, /rest/config/gui
|
||
.sp
|
||
\fBGET\fP returns the respective object, \fBPUT\fP replaces the entire object and
|
||
\fBPATCH\fP replaces only the given child objects.
|
||
.SH CLUSTER ENDPOINTS
|
||
.sp
|
||
Concerns the mesh network structure.
|
||
.SS DELETE /rest/cluster/pending/devices
|
||
.sp
|
||
New in version 1.18.0.
|
||
|
||
.sp
|
||
Remove records about a pending remote device which tried to connect. Valid
|
||
values for the \fBdevice\fP parameter are those from the corresponding
|
||
cluster\-pending\-devices\-get endpoint.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ curl \-X DELETE \-H "X\-API\-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Returns status 200 and no content upon success, or status 500 and a
|
||
plain text error on failure. A /events/pendingdeviceschanged
|
||
event will be generated in response.
|
||
.sp
|
||
For a more permanent effect, also for future connections from the same
|
||
device ID, the device should be ignored in the configuration instead.
|
||
.SS GET /rest/cluster/pending/devices
|
||
.sp
|
||
New in version 1.13.0.
|
||
|
||
.sp
|
||
Lists remote devices which have tried to connect, but are not yet
|
||
configured in our instance.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
|
||
"time": "2020\-03\-18T11:43:07Z",
|
||
"name": "Friend Joe",
|
||
"address": "192.168.1.2:22000"
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS DELETE /rest/cluster/pending/folders
|
||
.sp
|
||
New in version 1.18.0.
|
||
|
||
.sp
|
||
Remove records about a pending folder announced from a remote device. Valid
|
||
values for the \fBfolder\fP and \fBdevice\fP parameters are those from the
|
||
corresponding cluster\-pending\-folders\-get endpoint. The \fBdevice\fP
|
||
parameter is optional and affects announcements of this folder from the given
|
||
device, or from \fIany\fP device if omitted.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ curl \-X DELETE \-H "X\-API\-Key: abc123" http://localhost:8384/rest/cluster/pending/folders?folder=cpkn4\-57ysy&device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Returns status 200 and no content upon success, or status 500 and a plain text
|
||
error on failure. A /events/pendingfolderschanged event will be
|
||
generated in response.
|
||
.sp
|
||
For a more permanent effect, also for future announcements of the same folder
|
||
ID, the folder should be ignored in the configuration
|
||
instead.
|
||
.SS GET /rest/cluster/pending/folders
|
||
.sp
|
||
New in version 1.13.0.
|
||
|
||
.sp
|
||
Lists folders which remote devices have offered to us, but are not yet
|
||
shared from our instance to them. Takes the optional \fBdevice\fP
|
||
parameter to only return folders offered by a specific remote device.
|
||
Other offering devices are also omitted from the result.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"cpkn4\-57ysy": {
|
||
"offeredBy": {
|
||
"P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
|
||
"time": "2020\-03\-18T11:43:07Z",
|
||
"label": "Joe\(aqs folder",
|
||
"receiveEncrypted": true,
|
||
"remoteEncrypted": false
|
||
},
|
||
"DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA": {
|
||
"time": "2020\-03\-01T10:12:13Z",
|
||
"label": "Jane\(aqs and Joe\(aqs folder",
|
||
"receiveEncrypted": false,
|
||
"remoteEncrypted": false
|
||
}
|
||
}
|
||
},
|
||
"abcde\-fghij": {
|
||
"offeredBy": {
|
||
"P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
|
||
"time": "2020\-03\-18T11:43:07Z",
|
||
"label": "MyPics",
|
||
"receiveEncrypted": false,
|
||
"remoteEncrypted": false
|
||
}
|
||
}
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH FOLDER ENDPOINTS
|
||
.sp
|
||
Runtime state of the individual shared folders.
|
||
.SS GET /rest/folder/errors
|
||
.sp
|
||
New in version 0.14.53.
|
||
|
||
.sp
|
||
Takes one mandatory parameter, \fBfolder\fP, and returns the list of errors
|
||
encountered during scanning or pulling.
|
||
.sp
|
||
The results can be paginated using the common pagination parameters\&.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"folder": "nnhic\-sxuae",
|
||
"errors": [
|
||
{
|
||
"path": "noperm.txt",
|
||
"error": "hashing: open /path/to/folder/noperm.txt: permission denied"
|
||
}
|
||
],
|
||
"page": 1,
|
||
"perpage": 100
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS GET /rest/folder/pullerrors (DEPRECATED)
|
||
.sp
|
||
Deprecated since version v0.14.53: This endpoint still works as before but is deprecated. Use
|
||
folder\-errors\-get instead, which returns the same information.
|
||
.sp
|
||
See \fI\%https://github.com/syncthing/syncthing/commit/d510e3cca3d5caae42121fa206b3decc981ae59e\fP
|
||
|
||
.SS GET /rest/folder/versions
|
||
.sp
|
||
New in version 0.14.44.
|
||
|
||
.sp
|
||
Takes one mandatory parameter, \fBfolder\fP, and returns the list of archived
|
||
files that could be recovered. How many versions are available depends on the
|
||
/users/versioning configuration. Each entry specifies when the file
|
||
version was archived as the \fBversionTime\fP, the \fBmodTime\fP when it was last
|
||
modified before being archived, and the size in bytes.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"dir1/dir2/bar": [
|
||
{
|
||
"versionTime": "2022\-02\-06T20:44:12+01:00",
|
||
"modTime": "2021\-01\-14T13:21:22+01:00",
|
||
"size": 4
|
||
}
|
||
],
|
||
"baz": [
|
||
{
|
||
"versionTime": "2022\-02\-06T20:44:20+01:00",
|
||
"modTime": "2021\-01\-14T13:23:49+01:00",
|
||
"size": 4
|
||
}
|
||
],
|
||
"foo": [
|
||
{
|
||
"versionTime": "2022\-02\-06T20:55:31+01:00",
|
||
"modTime": "2022\-02\-06T20:44:13+01:00",
|
||
"size": 4
|
||
},
|
||
{
|
||
"versionTime": "2022\-02\-06T20:44:20+01:00",
|
||
"modTime": "2021\-01\-14T13:21:16+01:00",
|
||
"size": 4
|
||
}
|
||
]
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS POST /rest/folder/versions
|
||
.sp
|
||
Restore archived versions of a given set of files. Expects an object with
|
||
attributes named after the relative file paths, with timestamps as values
|
||
matching valid \fBversionTime\fP entries in the corresponding
|
||
folder\-versions\-get response object.
|
||
.sp
|
||
Takes the mandatory parameter \fBfolder\fP (folder ID). Returns an object
|
||
containing any error messages that occurred during restoration of the file, with
|
||
the file path as attribute name.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
curl \-X POST \-H X\-API\-key:... http://127.0.0.1:8384/rest/folder/versions?folder=default \-d \(aq{
|
||
"dir1/dir2/bar": "2022\-02\-06T20:44:12+01:00",
|
||
"baz": "2022\-02\-06T20:44:20+01:00"
|
||
}\(aq
|
||
.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=j663y\-3ct3e&prefix=DCIM&levels=2
|
||
[
|
||
{
|
||
"modTime" : "2020\-10\-02T23:48:52.076996974+02:00",
|
||
"name" : "100ANDRO",
|
||
"size" : 128,
|
||
"type" : "FILE_INFO_TYPE_DIRECTORY"
|
||
},
|
||
{
|
||
"children" : [
|
||
{
|
||
"modTime" : "2020\-12\-16T23:31:34.5009668+01:00",
|
||
"name" : "IMG_20201114_124821.jpg",
|
||
"size" : 10682189,
|
||
"type" : "FILE_INFO_TYPE_FILE"
|
||
},
|
||
{
|
||
"modTime" : "2020\-12\-16T23:31:35.0106367+01:00",
|
||
"name" : "IMG_20201213_122451.jpg",
|
||
"size" : 7936351,
|
||
"type" : "FILE_INFO_TYPE_FILE"
|
||
},
|
||
{
|
||
"modTime" : "2020\-12\-13T12:25:05.017097469+01:00",
|
||
"name" : "IMG_20201213_122504.jpg",
|
||
"size" : 8406507,
|
||
"type" : "FILE_INFO_TYPE_FILE"
|
||
},
|
||
{
|
||
"modTime" : "2020\-12\-13T12:25:06.127097469+01:00",
|
||
"name" : "IMG_20201213_122505.jpg",
|
||
"size" : 8381931,
|
||
"type" : "FILE_INFO_TYPE_FILE"
|
||
},
|
||
{
|
||
"modTime" : "2020\-12\-13T12:53:29.707298401+01:00",
|
||
"name" : "IMG_20201213_125329.jpg",
|
||
"size" : 4388331,
|
||
"type" : "FILE_INFO_TYPE_FILE"
|
||
},
|
||
],
|
||
"modTime" : "2020\-10\-09T13:04:42.4410738+02:00",
|
||
"name" : "Camera",
|
||
"size" : 128,
|
||
"type" : "FILE_INFO_TYPE_DIRECTORY"
|
||
},
|
||
]
|
||
.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) and byte / item counts. Takes
|
||
optional \fBdevice\fP and \fBfolder\fP parameters:
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fBfolder\fP specifies the folder ID to calculate completion for. An empty
|
||
or absent \fBfolder\fP parameter means all folders as an aggregate.
|
||
.IP \(bu 2
|
||
\fBdevice\fP specifies the device ID to calculate completion for. An empty
|
||
or absent \fBdevice\fP parameter means the local device.
|
||
.UNINDENT
|
||
.sp
|
||
If a device is specified but no folder, completion is calculated for all
|
||
folders shared with that device.
|
||
.SS Example Queries
|
||
.sp
|
||
Completion status for folder \fBabcd\-1234\fP on device \fBI6KAH76\-...\-3PSROAU\fP:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
/rest/db/completion?folder=abcd\-1234&device=I6KAH76\-...\-3PSROAU
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Aggregated completion status for device \fBI6KAH76\-...\-3PSROAU\fP (all folders shared with them):
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
/rest/db/completion?device=I6KAH76\-...\-3PSROAU
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Completion status for folder \fBabcd\-1234\fP on the local device:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
/rest/db/completion?folder=abcd\-1234
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Aggregated completion status for all folders on the local device:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
/rest/db/completion
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Example Response
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"completion": 99.9937565835,
|
||
"globalBytes": 156793013575,
|
||
"needBytes": 9789241,
|
||
"globalItems": 7823,
|
||
"needItems": 412,
|
||
"needDeletes": 0,
|
||
"remoteState": "valid",
|
||
"sequence": 12
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
New in version 1.8.0: The ability to aggregate multiple folders by leaving out the folder ID.
|
||
Querying data for the local device by leaving out the device ID. Returning
|
||
the \fBglobalItems\fP counter in the response.
|
||
|
||
.sp
|
||
New in version 1.20.0: Indication whether the remote device has accepted the folder (shares it with
|
||
us) as well, and whether it is paused. The \fBremoteState\fP field is
|
||
meaningless for aggregated responses, \fBunknown\fP when the remote device is
|
||
not connected. Otherwise it can be either \fBpaused\fP, \fBnotSharing\fP, or
|
||
\fBvalid\fP if the remote is sharing back.
|
||
|
||
.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. \fBlocal\fP and
|
||
\fBglobal\fP refer to the current file on disk and the globally newest file,
|
||
respectively.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"availability": [
|
||
{
|
||
"id": "ITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM",
|
||
"fromTemporary": false
|
||
}
|
||
],
|
||
"global": { /* a file entry */ },
|
||
"local": { /* a file entry */ }
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
A file entry looks like this:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
{
|
||
"deleted": false,
|
||
"ignored": false,
|
||
"inodeChange": "1970\-01\-01T01:00:00+01:00",
|
||
"invalid": false,
|
||
"localFlags": 0,
|
||
"modified": "2022\-09\-28T08:07:19.979723+02:00",
|
||
"modifiedBy": "523ITIE",
|
||
"mustRescan": false,
|
||
"name": "img",
|
||
"noPermissions": false,
|
||
"numBlocks": 0,
|
||
"permissions": "0755",
|
||
"platform": { /* platform specific data */ },
|
||
"sequence": 914,
|
||
"size": 128,
|
||
"type": "FILE_INFO_TYPE_DIRECTORY",
|
||
"version": [
|
||
"523ITIE:1664345275"
|
||
]
|
||
},
|
||
"mtime": {
|
||
"err": null,
|
||
"value": {
|
||
"real": "0001\-01\-01T00:00:00Z",
|
||
"virtual": "0001\-01\-01T00:00:00Z"
|
||
}
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Platform specific data may be ownership, extended attributes, etc. and is
|
||
divided into entries per operating system / platform. An example platform
|
||
entry containing ownership information for Unix systems and an extended
|
||
attribute for macOS (“darwin”) looks as follows:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"darwin": {
|
||
"xattrs": [
|
||
{
|
||
"name": "net.kastelo.xattrtest",
|
||
"value": "aGVsbG8="
|
||
}
|
||
]
|
||
},
|
||
"freebsd": null,
|
||
"linux": null,
|
||
"netbsd": null,
|
||
"unix": {
|
||
"gid": 20,
|
||
"groupName": "staff",
|
||
"ownerName": "jb",
|
||
"uid": 501
|
||
},
|
||
"windows": null
|
||
}
|
||
.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 db\-ignores\-get 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/localchanged
|
||
.sp
|
||
New in version 0.14.55.
|
||
|
||
.sp
|
||
Takes one mandatory parameter, \fBfolder\fP, and returns the list of files which
|
||
were changed locally in a receive\-only folder. Thus they differ from the global
|
||
state and could be reverted by pulling from remote devices again, see
|
||
db\-revert\-post\&.
|
||
.sp
|
||
The results can be paginated using the common pagination parameters\&.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"files": [
|
||
{
|
||
"flags": "0755",
|
||
"sequence": 6,
|
||
"modified": "2015\-04\-20T23:06:12+09:00",
|
||
"name": "ls",
|
||
"size": 34640,
|
||
"version": [
|
||
"5157751870738175669:1"
|
||
]
|
||
}
|
||
],
|
||
"page": 1,
|
||
"perpage": 100
|
||
}
|
||
.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/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
|
||
The results can be paginated using the common pagination parameters\&. 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
|
||
\fBNOTE:\fP
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
Return format changed in version 0.14.43, removing the \fBtotal\fP count
|
||
attribute.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.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
|
||
}
|
||
.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 send only folder. Override means to make the local
|
||
version latest, overriding changes made on other devices. This API call does
|
||
nothing if the folder is not a send only folder.
|
||
.sp
|
||
Takes the mandatory parameter \fIfolder\fP (folder ID).
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
curl \-X POST \-H X\-API\-key:... 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 db\-need\-get\&.
|
||
.SS GET /rest/db/remoteneed
|
||
.sp
|
||
New in version 0.14.43.
|
||
|
||
.sp
|
||
Takes the mandatory parameters \fBfolder\fP and \fBdevice\fP, and returns the list
|
||
of files which are needed by that remote device in order for it to become in
|
||
sync with the shared folder.
|
||
.sp
|
||
The results can be paginated using the common pagination parameters\&.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"files": [
|
||
{
|
||
"flags": "0755",
|
||
"sequence": 6,
|
||
"modified": "2015\-04\-20T23:06:12+09:00",
|
||
"name": "ls",
|
||
"size": 34640,
|
||
"version": [
|
||
"5157751870738175669:1"
|
||
]
|
||
}
|
||
],
|
||
"page": 1,
|
||
"perpage": 100
|
||
}
|
||
.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/revert
|
||
.sp
|
||
New in version 0.14.50.
|
||
|
||
.sp
|
||
Request revert of a receive only folder. Reverting a folder means to undo
|
||
all local changes. This API call does nothing if the folder is not a receive
|
||
only folder.
|
||
.sp
|
||
Takes the mandatory parameter \fIfolder\fP (folder ID).
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
curl \-X POST \-H X\-API\-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS POST /rest/db/scan
|
||
.sp
|
||
Request immediate scan. Takes the optional parameters \fBfolder\fP (folder ID),
|
||
\fBsub\fP (path relative to the folder root) and \fBnext\fP (time in seconds). If
|
||
\fBfolder\fP is omitted or empty all folders are scanned. If \fBsub\fP is given,
|
||
only this path (and children, in case it’s a directory) is scanned. The \fBnext\fP
|
||
argument delays Syncthing’s 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
|
||
{
|
||
"globalBytes": 0,
|
||
"globalDeleted": 0,
|
||
"globalDirectories": 0,
|
||
"globalFiles": 0,
|
||
"globalSymlinks": 0,
|
||
"globalTotalItems": 0,
|
||
"ignorePatterns": false,
|
||
"inSyncBytes": 0,
|
||
"inSyncFiles": 0,
|
||
"invalid": "",
|
||
"localBytes": 0,
|
||
"localDeleted": 0,
|
||
"localDirectories": 0,
|
||
"localFiles": 0,
|
||
"localSymlinks": 0,
|
||
"localTotalItems": 0,
|
||
"needBytes": 0,
|
||
"needDeletes": 0,
|
||
"needDirectories": 0,
|
||
"needFiles": 0,
|
||
"needSymlinks": 0,
|
||
"needTotalItems": 0,
|
||
"pullErrors": 0,
|
||
"receiveOnlyChangedBytes": 0,
|
||
"receiveOnlyChangedDeletes": 0,
|
||
"receiveOnlyChangedDirectories": 0,
|
||
"receiveOnlyChangedFiles": 0,
|
||
"receiveOnlyChangedSymlinks": 0,
|
||
"receiveOnlyTotalItems": 0,
|
||
"sequence": 0,
|
||
"state": "idle",
|
||
"stateChanged": "2018\-08\-08T07:04:57.301064781+02:00",
|
||
"version": 0
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The various fields have the following meaning:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B global*:
|
||
Data in the cluster latest version.
|
||
.TP
|
||
.B inSync*:
|
||
Data that is locally the same as the cluster latest version.
|
||
.TP
|
||
.B local*:
|
||
Data that is locally present, regardless of whether it’s the same or different version as the cluster latest version.
|
||
.TP
|
||
.B need*:
|
||
Data that is needed to become up to date with the cluster latest version (i.e., data that is out of sync).
|
||
.TP
|
||
.B receiveOnlyChanged*:
|
||
Data that has changed locally in a receive only folder, and thus not been sent to the cluster.
|
||
.TP
|
||
.B invalid:
|
||
Deprecated, always empty.
|
||
.TP
|
||
.B pullErrors:
|
||
The number of files that failed to sync during the last sync operations.
|
||
.TP
|
||
.B sequence:
|
||
The current folder sequence number.
|
||
.TP
|
||
.B state:
|
||
The current folder state.
|
||
.TP
|
||
.B stateChanged:
|
||
When the folder state last changed.
|
||
.TP
|
||
.B version:
|
||
Deprecated, equivalent to the sequence number.
|
||
.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 EVENT ENDPOINTS
|
||
.SS GET /rest/events
|
||
.sp
|
||
To receive events, perform a HTTP GET of \fB/rest/events\fP\&.
|
||
.sp
|
||
To filter the event list, in effect creating a specific subscription for only
|
||
the desired event types, add a parameter \fBevents=EventTypeA,EventTypeB,...\fP
|
||
where the event types are any of the event\-types\&. If no filter is
|
||
specified, all events \fIexcept\fP /events/localchangedetected and
|
||
/events/remotechangedetected are included.
|
||
.sp
|
||
The optional parameter \fBsince=<lastSeenID>\fP sets the ID of the last event
|
||
you’ve already seen. Syncthing returns a JSON encoded array of event objects,
|
||
starting at the event just after the one with this last seen ID. The default
|
||
value is 0, which returns all events. There is a limit to the number of events
|
||
buffered, so if the rate of events is high or the time between polling calls is
|
||
long some events might be missed. This can be detected by noting a discontinuity
|
||
in the event IDs.
|
||
.sp
|
||
If no new events are produced since \fB<lastSeenID>\fP, the HTTP call blocks and
|
||
waits for new events to happen before returning. By default it times out after
|
||
60 seconds returning an empty array. The time out duration can be customized
|
||
with the optional parameter \fBtimeout=<seconds>\fP\&.
|
||
.sp
|
||
To receive only a limited number of events, add the \fBlimit=<n>\fP parameter with a
|
||
suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This
|
||
can be used to catch up with the latest event ID after a disconnection for
|
||
example: \fB/rest/events?since=0&limit=1\fP\&.
|
||
.SS GET /rest/events/disk
|
||
.sp
|
||
This convenience endpoint provides the same event stream, but pre\-filtered to show
|
||
only /events/localchangedetected and /events/remotechangedetected
|
||
event types. The \fBevents\fP parameter is not used.
|
||
.SH STATISTICS ENDPOINTS
|
||
.SS GET /rest/stats/device
|
||
.sp
|
||
Returns general statistics about devices. Currently, only contains the
|
||
time the device was last seen and the last connection duration.
|
||
.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"
|
||
"lastConnectionDurationS": 556335.421708141
|
||
}
|
||
}
|
||
.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
|
||
{
|
||
"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,
|
||
"sendonly" : 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 DEBUG ENDPOINTS
|
||
.SS Debug Endpoints
|
||
.sp
|
||
These endpoints require the \fBgui.debugging\fP configuration option to
|
||
be enabled and yield an access denied error code otherwise.
|
||
.SS GET /rest/debug/peerCompletion
|
||
.sp
|
||
Summarizes the completion percentage for each remote device. Returns an object
|
||
with device IDs as keys and an integer percentage as values.
|
||
.SS GET /rest/debug/httpmetrics
|
||
.sp
|
||
Returns statistics about each served REST API endpoint, to diagnose how much
|
||
time was spent generating the responses.
|
||
.SS GET /rest/debug/cpuprof
|
||
.sp
|
||
Used to capture a profile of what Syncthing is doing on the CPU. See
|
||
/users/profiling\&.
|
||
.SS GET /rest/debug/heapprof
|
||
.sp
|
||
Used to capture a profile of what Syncthing is doing with the heap memory. See
|
||
/users/profiling\&.
|
||
.SS GET /rest/debug/support
|
||
.sp
|
||
Collects information about the running instance for troubleshooting purposes.
|
||
Returns a “support bundle” as a zipped archive, which should be sent to the
|
||
developers after verifying it contains no sensitive personal information.
|
||
Credentials for the web GUI and the API key are automatically redacted already.
|
||
.SS GET /rest/debug/file
|
||
.sp
|
||
Shows diagnostics about a certain file in a shared folder. Takes the \fBfolder\fP
|
||
(folder ID) and \fBfile\fP (folder relative path) parameters.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
$ curl \-H X\-API\-Key:... "http://localhost:8384/rest/debug/file?folder=default&file=foo/bar"
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The returned object contains the same info as db\-file\-get, plus a summary
|
||
of \fBglobalVersions\fP\&.
|
||
.SH NOAUTH ENDPOINTS
|
||
.sp
|
||
Calls that do not require authentication.
|
||
.SS GET /rest/noauth/health
|
||
.sp
|
||
Returns a \fB{"status": "OK"}\fP object.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"status": "OK"
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH AUTHOR
|
||
The Syncthing Authors
|
||
.SH COPYRIGHT
|
||
2014-2019, The Syncthing Authors
|
||
.\" Generated by docutils manpage writer.
|
||
.
|