1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990 |
- .\" 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" "Sep 14, 2022" "v1.21.0" "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).
- .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 and 1.19.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" : {
- "at" : "2015\-11\-07T17:29:47.691637262+01:00",
- "inBytesTotal" : 1479,
- "outBytesTotal" : 1318,
- },
- "connections" : {
- "YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC" : {
- "connected" : true,
- "inBytesTotal" : 556,
- "paused" : false,
- "at" : "2015\-11\-07T17:29:47.691548971+01:00",
- "startedAt" : "2015\-11\-07T00:09:47Z",
- "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",
- "startedAt" : "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",
- "startedAt" : "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. 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\%d510e3cca3d5caae42121fa206b3decc981ae59e\fP <\fBhttps://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.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .nf
- .ft C
- {
- "availability": [
- {
- "id": "ITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM",
- "fromTemporary": false
- }
- ],
- "global": {
- "deleted": false,
- "ignored": false,
- "invalid": false,
- "localFlags": 0,
- "modified": "2018\-08\-18T12:21:13.836784059+02:00",
- "modifiedBy": "SYNO4VL",
- "mustRescan": false,
- "name": "testfile",
- "noPermissions": false,
- "numBlocks": 1,
- "permissions": "0755",
- "sequence": 107499,
- "size": 1234,
- "type": 0,
- "version": [
- "SYNO4VL:1"
- ]
- },
- "local": {
- "deleted": false,
- "ignored": false,
- "invalid": false,
- "localFlags": 0,
- "modified": "2018\-08\-18T12:21:13.836784059+02:00",
- "modifiedBy": "SYNO4VL",
- "mustRescan": false,
- "name": "testfile",
- "noPermissions": false,
- "numBlocks": 1,
- "permissions": "0755",
- "sequence": 111038,
- "size": 1234,
- "type": 0,
- "version": [
- "SYNO4VL: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 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.
- .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
- {
- "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 precentage 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 AUTHOR
- The Syncthing Authors
- .SH COPYRIGHT
- 2014-2019, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|