syncthing-rest-api.7 42 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559
  1. .\" Man page generated from reStructuredText.
  2. .
  3. .
  4. .nr rst2man-indent-level 0
  5. .
  6. .de1 rstReportMargin
  7. \\$1 \\n[an-margin]
  8. level \\n[rst2man-indent-level]
  9. level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  10. -
  11. \\n[rst2man-indent0]
  12. \\n[rst2man-indent1]
  13. \\n[rst2man-indent2]
  14. ..
  15. .de1 INDENT
  16. .\" .rstReportMargin pre:
  17. . RS \\$1
  18. . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  19. . nr rst2man-indent-level +1
  20. .\" .rstReportMargin post:
  21. ..
  22. .de UNINDENT
  23. . RE
  24. .\" indent \\n[an-margin]
  25. .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  26. .nr rst2man-indent-level -1
  27. .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  28. .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  29. ..
  30. .TH "SYNCTHING-REST-API" "7" "Jun 14, 2021" "v1" "Syncthing"
  31. .SH NAME
  32. syncthing-rest-api \- REST API
  33. .sp
  34. Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
  35. the GUI (from Javascript) and can be used by other processes wishing to control
  36. Syncthing. In most cases both the input and output data is in JSON format. The
  37. interface is subject to change.
  38. .SH API KEY
  39. .sp
  40. To use the REST API an API key must be set and used. The API key can be
  41. generated in the GUI, or set in the \fBconfiguration/gui/apikey\fP element in
  42. the configuration file. To use an API key, set the request header
  43. \fBX\-API\-Key\fP to the API key value. For example, \fBcurl \-X POST \-H
  44. "X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be used to invoke
  45. with \fBcurl\fP (add \fB\-k\fP flag when using HTTPS with a Syncthing generated or self signed certificate).
  46. .SH SYSTEM ENDPOINTS
  47. .SS GET /rest/system/browse
  48. .sp
  49. Returns a list of directories matching the path given by the optional parameter
  50. \fBcurrent\fP\&. The path can use \fI\%patterns as described in Go’s filepath package\fP <\fBhttps://golang.org/pkg/path/filepath/#Match\fP>\&. A ‘*’ will always be appended
  51. to the given path (e.g. \fB/tmp/\fP matches all its subdirectories). If the option
  52. \fBcurrent\fP is not given, filesystem root paths are returned.
  53. .INDENT 0.0
  54. .INDENT 3.5
  55. .sp
  56. .nf
  57. .ft C
  58. $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse | json_pp
  59. [
  60. "/"
  61. ]
  62. $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/ | json_pp
  63. [
  64. "/var/backups/",
  65. "/var/cache/",
  66. "/var/lib/",
  67. "/var/local/",
  68. "/var/lock/",
  69. "/var/log/",
  70. "/var/mail/",
  71. "/var/opt/",
  72. "/var/run/",
  73. "/var/spool/",
  74. "/var/tmp/"
  75. ]
  76. $ curl \-H "X\-API\-Key: yourkey" localhost:8384/rest/system/browse?current=/var/*o | json_pp
  77. [
  78. "/var/local/",
  79. "/var/lock/",
  80. "/var/log/",
  81. "/var/opt/",
  82. "/var/spool/"
  83. ]
  84. .ft P
  85. .fi
  86. .UNINDENT
  87. .UNINDENT
  88. .SS GET /rest/system/config
  89. .sp
  90. Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use rest\-config
  91. instead.
  92. .sp
  93. Returns the current configuration.
  94. .INDENT 0.0
  95. .INDENT 3.5
  96. .sp
  97. .nf
  98. .ft C
  99. {
  100. "version": 30,
  101. "folders": [
  102. {
  103. "id": "GXWxf\-3zgnU",
  104. "label": "MyFolder",
  105. "filesystemType": "basic",
  106. "path": "...",
  107. "type": "sendreceive",
  108. "devices": [
  109. {
  110. "deviceID": "...",
  111. "introducedBy": ""
  112. }
  113. ],
  114. "rescanIntervalS": 60,
  115. "fsWatcherEnabled": false,
  116. "fsWatcherDelayS": 10,
  117. "ignorePerms": false,
  118. "autoNormalize": true,
  119. "minDiskFree": {
  120. "value": 1,
  121. "unit": "%"
  122. },
  123. "versioning": {
  124. "type": "simple",
  125. "params": {
  126. "keep": "5"
  127. }
  128. },
  129. "copiers": 0,
  130. "pullerMaxPendingKiB": 0,
  131. "hashers": 0,
  132. "order": "random",
  133. "ignoreDelete": false,
  134. "scanProgressIntervalS": 0,
  135. "pullerPauseS": 0,
  136. "maxConflicts": 10,
  137. "disableSparseFiles": false,
  138. "disableTempIndexes": false,
  139. "paused": false,
  140. "weakHashThresholdPct": 25,
  141. "markerName": ".stfolder",
  142. "copyOwnershipFromParent": false,
  143. "modTimeWindowS": 0
  144. }
  145. ],
  146. "devices": [
  147. {
  148. "deviceID": "...",
  149. "name": "Laptop",
  150. "addresses": [
  151. "dynamic",
  152. "tcp://192.168.1.2:22000"
  153. ],
  154. "compression": "metadata",
  155. "certName": "",
  156. "introducer": false,
  157. "skipIntroductionRemovals": false,
  158. "introducedBy": "",
  159. "paused": false,
  160. "allowedNetworks": [],
  161. "autoAcceptFolders": false,
  162. "maxSendKbps": 0,
  163. "maxRecvKbps": 0,
  164. "ignoredFolders": [],
  165. "maxRequestKiB": 0
  166. }
  167. ],
  168. "gui": {
  169. "enabled": true,
  170. "address": "127.0.0.1:8384",
  171. "user": "Username",
  172. "password": "$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6",
  173. "authMode": "static",
  174. "useTLS": false,
  175. "apiKey": "pGahcht56664QU5eoFQW6szbEG6Ec2Cr",
  176. "insecureAdminAccess": false,
  177. "theme": "default",
  178. "debugging": false,
  179. "insecureSkipHostcheck": false,
  180. "insecureAllowFrameLoading": false
  181. },
  182. "ldap": {
  183. "address": "",
  184. "bindDN": "",
  185. "transport": "plain",
  186. "insecureSkipVerify": false
  187. },
  188. "options": {
  189. "listenAddresses": [
  190. "default"
  191. ],
  192. "globalAnnounceServers": [
  193. "default"
  194. ],
  195. "globalAnnounceEnabled": true,
  196. "localAnnounceEnabled": true,
  197. "localAnnouncePort": 21027,
  198. "localAnnounceMCAddr": "[ff12::8384]:21027",
  199. "maxSendKbps": 0,
  200. "maxRecvKbps": 0,
  201. "reconnectionIntervalS": 60,
  202. "relaysEnabled": true,
  203. "relayReconnectIntervalM": 10,
  204. "startBrowser": false,
  205. "natEnabled": true,
  206. "natLeaseMinutes": 60,
  207. "natRenewalMinutes": 30,
  208. "natTimeoutSeconds": 10,
  209. "urAccepted": \-1,
  210. "urSeen": 2,
  211. "urUniqueId": "",
  212. "urURL": "https://data.syncthing.net/newdata",
  213. "urPostInsecurely": false,
  214. "urInitialDelayS": 1800,
  215. "restartOnWakeup": true,
  216. "autoUpgradeIntervalH": 12,
  217. "upgradeToPreReleases": false,
  218. "keepTemporariesH": 24,
  219. "cacheIgnoredFiles": false,
  220. "progressUpdateIntervalS": 5,
  221. "limitBandwidthInLan": false,
  222. "minHomeDiskFree": {
  223. "value": 1,
  224. "unit": "%"
  225. },
  226. "releasesURL": "https://upgrades.syncthing.net/meta.json",
  227. "alwaysLocalNets": [],
  228. "overwriteRemoteDeviceNamesOnConnect": false,
  229. "tempIndexMinBlocks": 10,
  230. "unackedNotificationIDs": [],
  231. "trafficClass": 0,
  232. "defaultFolderPath": "~",
  233. "setLowPriority": true,
  234. "maxFolderConcurrency": 0,
  235. "crURL": "https://crash.syncthing.net/newcrash",
  236. "crashReportingEnabled": true,
  237. "stunKeepaliveStartS": 180,
  238. "stunKeepaliveMinS": 20,
  239. "stunServers": [
  240. "default"
  241. ],
  242. "databaseTuning": "auto",
  243. "maxConcurrentIncomingRequestKiB": 0
  244. },
  245. "remoteIgnoredDevices": []
  246. }
  247. .ft P
  248. .fi
  249. .UNINDENT
  250. .UNINDENT
  251. .SS GET /rest/system/config/insync
  252. .sp
  253. Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use
  254. rest\-config\-insync instead.
  255. .sp
  256. Returns whether the config is in sync, i.e. whether the running
  257. configuration is the same as that on disk.
  258. .INDENT 0.0
  259. .INDENT 3.5
  260. .sp
  261. .nf
  262. .ft C
  263. {
  264. "configInSync": true
  265. }
  266. .ft P
  267. .fi
  268. .UNINDENT
  269. .UNINDENT
  270. .SS POST /rest/system/config
  271. .sp
  272. Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use rest\-config
  273. instead.
  274. .sp
  275. Post the full contents of the configuration, in the same format as returned by
  276. the corresponding GET request. When posting the configuration succeeds,
  277. the posted configuration is immediately applied, except for changes that require a restart. Query
  278. rest\-config\-insync to check if a restart is required.
  279. .sp
  280. This endpoint is the main point to control Syncthing, even if the change only
  281. concerns a very small part of the config: The usual workflow is to get the
  282. config, modify the needed parts and post it again.
  283. .SS GET /rest/system/connections
  284. .sp
  285. \fBNOTE:\fP
  286. .INDENT 0.0
  287. .INDENT 3.5
  288. Return format changed in 0.13.0.
  289. .UNINDENT
  290. .UNINDENT
  291. .sp
  292. Returns the list of configured devices and some metadata associated
  293. with them. The list also contains the local device itself as not connected.
  294. .sp
  295. The connection types are \fBTCP (Client)\fP, \fBTCP (Server)\fP, \fBRelay (Client)\fP and \fBRelay (Server)\fP\&.
  296. .INDENT 0.0
  297. .INDENT 3.5
  298. .sp
  299. .nf
  300. .ft C
  301. {
  302. "total" : {
  303. "paused" : false,
  304. "clientVersion" : "",
  305. "at" : "2015\-11\-07T17:29:47.691637262+01:00",
  306. "connected" : false,
  307. "inBytesTotal" : 1479,
  308. "type" : "",
  309. "outBytesTotal" : 1318,
  310. "address" : ""
  311. },
  312. "connections" : {
  313. "YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC" : {
  314. "connected" : true,
  315. "inBytesTotal" : 556,
  316. "paused" : false,
  317. "at" : "2015\-11\-07T17:29:47.691548971+01:00",
  318. "clientVersion" : "v0.12.1",
  319. "address" : "127.0.0.1:22002",
  320. "type" : "TCP (Client)",
  321. "outBytesTotal" : 550
  322. },
  323. "DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA" : {
  324. "outBytesTotal" : 0,
  325. "type" : "",
  326. "address" : "",
  327. "at" : "0001\-01\-01T00:00:00Z",
  328. "clientVersion" : "",
  329. "paused" : false,
  330. "inBytesTotal" : 0,
  331. "connected" : false
  332. },
  333. "UYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4" : {
  334. "address" : "",
  335. "type" : "",
  336. "outBytesTotal" : 0,
  337. "connected" : false,
  338. "inBytesTotal" : 0,
  339. "paused" : false,
  340. "at" : "0001\-01\-01T00:00:00Z",
  341. "clientVersion" : ""
  342. }
  343. }
  344. }
  345. .ft P
  346. .fi
  347. .UNINDENT
  348. .UNINDENT
  349. .SS GET /rest/system/debug
  350. .sp
  351. New in version 0.12.0.
  352. .sp
  353. Returns the set of debug facilities and which of them are currently enabled.
  354. .INDENT 0.0
  355. .INDENT 3.5
  356. .sp
  357. .nf
  358. .ft C
  359. {
  360. "enabled": [
  361. "beacon"
  362. ],
  363. "facilities": {
  364. "beacon": "Multicast and broadcast discovery",
  365. "config": "Configuration loading and saving",
  366. "connections": "Connection handling",
  367. "db": "The database layer",
  368. "dialer": "Dialing connections",
  369. "discover": "Remote device discovery",
  370. "events": "Event generation and logging",
  371. "http": "REST API",
  372. "main": "Main package",
  373. "model": "The root hub",
  374. "protocol": "The BEP protocol",
  375. "relay": "Relay connection handling",
  376. "scanner": "File change detection and hashing",
  377. "stats": "Persistent device and folder statistics",
  378. "sync": "Mutexes",
  379. "upgrade": "Binary upgrades",
  380. "upnp": "UPnP discovery and port mapping",
  381. "versioner": "File versioning"
  382. }
  383. }
  384. .ft P
  385. .fi
  386. .UNINDENT
  387. .UNINDENT
  388. .SS POST /rest/system/debug
  389. .sp
  390. New in version 0.12.0.
  391. .sp
  392. Enables or disables debugging for specified facilities. Give one or both of
  393. \fBenable\fP and \fBdisable\fP query parameters, with comma separated facility
  394. names. To disable debugging of the beacon and discovery packages, and enable it
  395. for config and db:
  396. .INDENT 0.0
  397. .INDENT 3.5
  398. .sp
  399. .nf
  400. .ft C
  401. $ curl \-H X\-API\-Key:abc123 \-X POST \(aqhttp://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db\(aq
  402. .ft P
  403. .fi
  404. .UNINDENT
  405. .UNINDENT
  406. .SS GET /rest/system/discovery
  407. .sp
  408. Returns the contents of the local discovery cache.
  409. .INDENT 0.0
  410. .INDENT 3.5
  411. .sp
  412. .nf
  413. .ft C
  414. {
  415. "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
  416. "192.162.129.11:22000"
  417. ]
  418. }
  419. .ft P
  420. .fi
  421. .UNINDENT
  422. .UNINDENT
  423. .SS POST /rest/system/discovery
  424. .sp
  425. \fBNOTE:\fP
  426. .INDENT 0.0
  427. .INDENT 3.5
  428. Removed in v0.12.0.
  429. .UNINDENT
  430. .UNINDENT
  431. .sp
  432. Post with the query parameters \fBdevice\fP and \fBaddr\fP to add entries to
  433. the discovery cache.
  434. .INDENT 0.0
  435. .INDENT 3.5
  436. .sp
  437. .nf
  438. .ft C
  439. curl \-X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
  440. # Or with the X\-API\-Key header:
  441. 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
  442. .ft P
  443. .fi
  444. .UNINDENT
  445. .UNINDENT
  446. .SS POST /rest/system/error/clear
  447. .sp
  448. Post with empty to body to remove all recent errors.
  449. .SS GET /rest/system/error
  450. .sp
  451. \fBNOTE:\fP
  452. .INDENT 0.0
  453. .INDENT 3.5
  454. Return format changed in 0.12.0.
  455. .UNINDENT
  456. .UNINDENT
  457. .sp
  458. Returns the list of recent errors.
  459. .INDENT 0.0
  460. .INDENT 3.5
  461. .sp
  462. .nf
  463. .ft C
  464. {
  465. "errors": [
  466. {
  467. "when": "2014\-09\-18T12:59:26.549953186+02:00",
  468. "message": "This is an error string"
  469. }
  470. ]
  471. }
  472. .ft P
  473. .fi
  474. .UNINDENT
  475. .UNINDENT
  476. .SS POST /rest/system/error
  477. .sp
  478. Post with an error message in the body (plain text) to register a new
  479. error. The new error will be displayed on any active GUI clients.
  480. .SS GET /rest/system/log
  481. .sp
  482. New in version 0.12.0.
  483. .sp
  484. Returns the list of recent log entries.
  485. .INDENT 0.0
  486. .INDENT 3.5
  487. .sp
  488. .nf
  489. .ft C
  490. {
  491. "messages": [
  492. {
  493. "when": "2014\-09\-18T12:59:26.549953186+02:00",
  494. "message": "This is a log entry"
  495. }
  496. ]
  497. }
  498. .ft P
  499. .fi
  500. .UNINDENT
  501. .UNINDENT
  502. .SS POST /rest/system/pause
  503. .sp
  504. Pause the given device or all devices.
  505. .sp
  506. Takes the optional parameter \fBdevice\fP (device ID). When omitted,
  507. pauses all devices. Returns status 200 and no content upon success, or status
  508. 500 and a plain text error on failure.
  509. .SS GET /rest/system/ping
  510. .sp
  511. Returns a \fB{"ping": "pong"}\fP object.
  512. .INDENT 0.0
  513. .INDENT 3.5
  514. .sp
  515. .nf
  516. .ft C
  517. {
  518. "ping": "pong"
  519. }
  520. .ft P
  521. .fi
  522. .UNINDENT
  523. .UNINDENT
  524. .SS POST /rest/system/ping
  525. .sp
  526. Returns a \fB{"ping": "pong"}\fP object.
  527. .SS POST /rest/system/reset
  528. .sp
  529. Post with empty body to erase the current index database and restart
  530. Syncthing. With no query parameters, the entire database is erased from disk.
  531. By specifying the \fBfolder\fP parameter with a valid folder ID, only
  532. information for that folder will be erased:
  533. .INDENT 0.0
  534. .INDENT 3.5
  535. .sp
  536. .nf
  537. .ft C
  538. $ curl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
  539. .ft P
  540. .fi
  541. .UNINDENT
  542. .UNINDENT
  543. .sp
  544. \fBCaution\fP: See \fB\-reset\-database\fP for \fB\&.stfolder\fP creation side\-effect and caution regarding mountpoints.
  545. .SS POST /rest/system/restart
  546. .sp
  547. Post with empty body to immediately restart Syncthing.
  548. .SS POST /rest/system/resume
  549. .sp
  550. Resume the given device or all devices.
  551. .sp
  552. Takes the optional parameter \fBdevice\fP (device ID). When omitted,
  553. resumes all devices. Returns status 200 and no content upon success, or status
  554. 500 and a plain text error on failure.
  555. .SS POST /rest/system/shutdown
  556. .sp
  557. Post with empty body to cause Syncthing to exit and not restart.
  558. .SS GET /rest/system/status
  559. .sp
  560. Returns information about current system status and resource usage. The CPU percent value has been deprecated from the API and will always report 0.
  561. .INDENT 0.0
  562. .INDENT 3.5
  563. .sp
  564. .nf
  565. .ft C
  566. {
  567. "alloc": 30618136,
  568. "connectionServiceStatus": {
  569. "dynamic+https://relays.syncthing.net/endpoint": {
  570. "error": null,
  571. "lanAddresses": [
  572. "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"
  573. ],
  574. "wanAddresses": [
  575. "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"
  576. ]
  577. },
  578. "tcp://0.0.0.0:22000": {
  579. "error": null,
  580. "lanAddresses": [
  581. "tcp://0.0.0.0:22000"
  582. ],
  583. "wanAddresses": [
  584. "tcp://0.0.0.0:22000"
  585. ]
  586. }
  587. },
  588. "cpuPercent": 0,
  589. "discoveryEnabled": true,
  590. "discoveryErrors": {
  591. "global@https://discovery\-v4\-1.syncthing.net/v2/": "500 Internal Server Error",
  592. "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)",
  593. "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)",
  594. "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",
  595. "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",
  596. "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"
  597. },
  598. "discoveryStatus": {
  599. "IPv4 local": {
  600. "error": null
  601. },
  602. "IPv6 local": {
  603. "error": null
  604. },
  605. "global@https://discovery\-v4\-1.syncthing.net/v2/": {
  606. "error": "500 Internal Server Error"
  607. },
  608. "global@https://discovery\-v4\-2.syncthing.net/v2/": {
  609. "error": "Post https://discovery\-v4\-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
  610. },
  611. "global@https://discovery\-v4\-3.syncthing.net/v2/": {
  612. "error": "Post https://discovery\-v4\-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
  613. },
  614. "global@https://discovery\-v6\-1.syncthing.net/v2/": {
  615. "error": "Post https://discovery\-v6\-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host"
  616. },
  617. "global@https://discovery\-v6\-2.syncthing.net/v2/": {
  618. "error": "Post https://discovery\-v6\-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host"
  619. },
  620. "global@https://discovery\-v6\-3.syncthing.net/v2/": {
  621. "error": "Post https://discovery\-v6\-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host"
  622. }
  623. },
  624. "discoveryMethods": 8,
  625. "goroutines": 49,
  626. "lastDialStatus": {
  627. "tcp://10.20.30.40": {
  628. "when": "2019\-05\-16T07:41:23Z",
  629. "error": "dial tcp 10.20.30.40:22000: i/o timeout"
  630. },
  631. "tcp://172.16.33.3:22000": {
  632. "when": "2019\-05\-16T07:40:43Z",
  633. "ok": true
  634. },
  635. "tcp://83.233.120.221:22000": {
  636. "when": "2019\-05\-16T07:41:13Z",
  637. "error": "dial tcp 83.233.120.221:22000: connect: connection refused"
  638. }
  639. },
  640. "myID": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2",
  641. "pathSeparator": "/",
  642. "startTime": "2016\-06\-06T19:41:43.039284753+02:00",
  643. "sys": 42092792,
  644. "themes": [
  645. "default",
  646. "dark"
  647. ],
  648. "tilde": "/Users/jb",
  649. "uptime": 2635
  650. }
  651. .ft P
  652. .fi
  653. .UNINDENT
  654. .UNINDENT
  655. .sp
  656. New in version 1.2.0: The \fBlastDialStatus\fP dictionary contains the last error (or \fBnull\fP for
  657. success) for each peer address that Syncthing has attempted to contact.
  658. The \fBconnectionServiceStatus\fP entries gained \fB"error": null\fP
  659. attributes where previously there would be no \fBerror\fP attribute at all
  660. in the success case.
  661. .sp
  662. New in version 1.18.0: The \fBdiscoveryStatus\fP dictionary lists all configured discovery methods, not
  663. only failed ones like the now deprecated \fBdiscoveryErrors\fP\&. Each entry is
  664. an object itself (for consistency with other fields), where a \fBnull\fP value
  665. for the \fBerror\fP attribute means the method is running successfully. This
  666. effectively deprecates the \fBdiscoveryMethods\fP attribute as well, which now
  667. always matches the number of entries in \fBdiscoveryStatus\fP\&.
  668. .SS GET /rest/system/upgrade
  669. .sp
  670. Checks for a possible upgrade and returns an object describing the
  671. newest version and upgrade possibility.
  672. .INDENT 0.0
  673. .INDENT 3.5
  674. .sp
  675. .nf
  676. .ft C
  677. {
  678. "latest": "v0.14.47",
  679. "majorNewer": false,
  680. "newer": true,
  681. "running": "v0.14.46"
  682. }
  683. .ft P
  684. .fi
  685. .UNINDENT
  686. .UNINDENT
  687. .SS POST /rest/system/upgrade
  688. .sp
  689. Perform an upgrade to the newest released version and restart. Does
  690. nothing if there is no newer version than currently running.
  691. .SS GET /rest/system/version
  692. .sp
  693. Returns the current Syncthing version information.
  694. .INDENT 0.0
  695. .INDENT 3.5
  696. .sp
  697. .nf
  698. .ft C
  699. {
  700. "arch": "amd64",
  701. "longVersion": "syncthing v0.10.27+3\-gea8c3de (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 11:01:29 UTC",
  702. "os": "darwin",
  703. "version": "v0.10.27+3\-gea8c3de"
  704. }
  705. .ft P
  706. .fi
  707. .UNINDENT
  708. .UNINDENT
  709. .SH CONFIG ENDPOINTS
  710. .SS Config Endpoints
  711. .sp
  712. New in version 1.12.0.
  713. .sp
  714. These endpoints facilitate access and modification of the configuration in a granular way. Config sent to the endpoints must be in the same
  715. format as returned by the corresponding GET request. When posting the
  716. configuration succeeds, the posted configuration is immediately applied, except
  717. for changes that require a restart. Query \fI\%/rest/config/restart\-required\fP to check if
  718. a restart is required.
  719. .sp
  720. For all endpoints supporting \fBPATCH\fP, it takes the existing config and
  721. unmarshals the given JSON object on top of it. This means all child objects will
  722. replace the existing objects, not extend them. For example for
  723. \fBRawListenAddresses\fP in options, which is an array of strings, sending
  724. \fB{RawListenAddresses: ["tcp://10.0.0.2"]}\fP will replace all existing listen
  725. addresses.
  726. .SS /rest/config
  727. .sp
  728. \fBGET\fP returns the entire config and \fBPUT\fP replaces it.
  729. .SS /rest/config/restart\-required
  730. .sp
  731. \fBGET\fP returns whether a restart of Syncthing is required for the current
  732. config to take effect.
  733. .SS /rest/config/folders, /rest/config/devices
  734. .sp
  735. \fBGET\fP returns all folders respectively devices as an array. \fBPUT\fP takes an array and
  736. \fBPOST\fP a single object. In both cases if a given folder/device already exists,
  737. it’s replaced, otherwise a new one is added.
  738. .SS /rest/config/folders/*id*, /rest/config/devices/*id*
  739. .sp
  740. Put the desired folder\- respectively device\-ID in place of *id*. \fBGET\fP
  741. returns the folder/device for the given ID, \fBPUT\fP replaces the entire config
  742. and \fBPATCH\fP replaces only the given child objects.
  743. .SS /rest/config/options, /rest/config/ldap, /rest/config/gui
  744. .sp
  745. \fBGET\fP returns the respective object, \fBPUT\fP replaces the entire object and
  746. \fBPATCH\fP replaces only the given child objects.
  747. .SH CLUSTER ENDPOINTS
  748. .sp
  749. Concerns the mesh network structure.
  750. .SS DELETE /rest/cluster/pending/devices
  751. .sp
  752. New in version 1.18.0.
  753. .sp
  754. Remove records about a pending remote device which tried to connect.
  755. Valid values for the \fBdevice\fP parameter are those from the
  756. corresponding /rest/cluster\-pending\-devices\-get endpoint.
  757. .INDENT 0.0
  758. .INDENT 3.5
  759. .sp
  760. .nf
  761. .ft C
  762. $ curl \-X DELETE \-H "X\-API\-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
  763. .ft P
  764. .fi
  765. .UNINDENT
  766. .UNINDENT
  767. .sp
  768. Returns status 200 and no content upon success, or status 500 and a
  769. plain text error on failure. A /events/pendingdeviceschanged
  770. event will be generated in response.
  771. .sp
  772. For a more permanent effect, also for future connections from the same
  773. device ID, the device should be ignored in the configuration instead.
  774. .SS GET /rest/cluster/pending/devices
  775. .sp
  776. New in version 1.13.0.
  777. .sp
  778. Lists remote devices which have tried to connect, but are not yet
  779. configured in our instance.
  780. .INDENT 0.0
  781. .INDENT 3.5
  782. .sp
  783. .nf
  784. .ft C
  785. {
  786. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  787. "time": "2020\-03\-18T11:43:07Z",
  788. "name": "Friend Joe",
  789. "address": "192.168.1.2:22000"
  790. }
  791. }
  792. .ft P
  793. .fi
  794. .UNINDENT
  795. .UNINDENT
  796. .SS DELETE /rest/cluster/pending/folders
  797. .sp
  798. New in version 1.18.0.
  799. .sp
  800. Remove records about a pending folder announced from a remote device.
  801. Valid values for the \fBfolder\fP and \fBdevice\fP parameters are those
  802. from the corresponding /rest/cluster\-pending\-folders\-get
  803. endpoint. The \fBdevice\fP parameter is optional and affects
  804. announcements of this folder from the given device, or from \fIany\fP
  805. device if omitted.
  806. .INDENT 0.0
  807. .INDENT 3.5
  808. .sp
  809. .nf
  810. .ft C
  811. $ 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
  812. .ft P
  813. .fi
  814. .UNINDENT
  815. .UNINDENT
  816. .sp
  817. Returns status 200 and no content upon success, or status 500 and a
  818. plain text error on failure. A /events/pendingfolderschanged
  819. event will be generated in response.
  820. .sp
  821. For a more permanent effect, also for future announcements of the same
  822. folder ID, the folder should be ignored in the configuration instead.
  823. .SS GET /rest/cluster/pending/folders
  824. .sp
  825. New in version 1.13.0.
  826. .sp
  827. Lists folders which remote devices have offered to us, but are not yet
  828. shared from our instance to them. Takes the optional \fBdevice\fP
  829. parameter to only return folders offered by a specific remote device.
  830. Other offering devices are also omitted from the result.
  831. .INDENT 0.0
  832. .INDENT 3.5
  833. .sp
  834. .nf
  835. .ft C
  836. {
  837. "cpkn4\-57ysy": {
  838. "offeredBy": {
  839. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  840. "time": "2020\-03\-18T11:43:07Z",
  841. "label": "Joe\(aqs folder"
  842. },
  843. "DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA": {
  844. "time": "2020\-03\-01T10:12:13Z",
  845. "label": "Jane\(aqs and Joe\(aqs folder"
  846. }
  847. }
  848. },
  849. "abcde\-fghij": {
  850. "offeredBy": {
  851. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  852. "time": "2020\-03\-18T11:43:07Z",
  853. "label": "MyPics"
  854. }
  855. }
  856. }
  857. }
  858. .ft P
  859. .fi
  860. .UNINDENT
  861. .UNINDENT
  862. .SH DATABASE ENDPOINTS
  863. .SS GET /rest/db/browse
  864. .sp
  865. Returns the directory tree of the global model. Directories are always
  866. JSON objects (map/dictionary), and files are always arrays of
  867. modification time and size. The first integer is the files modification
  868. time, and the second integer is the file size.
  869. .sp
  870. The call takes one mandatory \fBfolder\fP parameter and two optional
  871. parameters. Optional parameter \fBlevels\fP defines how deep within the
  872. tree we want to dwell down (0 based, defaults to unlimited depth)
  873. Optional parameter \fBprefix\fP defines a prefix within the tree where to
  874. start building the structure.
  875. .INDENT 0.0
  876. .INDENT 3.5
  877. .sp
  878. .nf
  879. .ft C
  880. $ curl \-s http://localhost:8384/rest/db/browse?folder=j663y\-3ct3e&prefix=DCIM&levels=2
  881. [
  882. {
  883. "modTime" : "2020\-10\-02T23:48:52.076996974+02:00",
  884. "name" : "100ANDRO",
  885. "size" : 128,
  886. "type" : "FILE_INFO_TYPE_DIRECTORY"
  887. },
  888. {
  889. "children" : [
  890. {
  891. "modTime" : "2020\-12\-16T23:31:34.5009668+01:00",
  892. "name" : "IMG_20201114_124821.jpg",
  893. "size" : 10682189,
  894. "type" : "FILE_INFO_TYPE_FILE"
  895. },
  896. {
  897. "modTime" : "2020\-12\-16T23:31:35.0106367+01:00",
  898. "name" : "IMG_20201213_122451.jpg",
  899. "size" : 7936351,
  900. "type" : "FILE_INFO_TYPE_FILE"
  901. },
  902. {
  903. "modTime" : "2020\-12\-13T12:25:05.017097469+01:00",
  904. "name" : "IMG_20201213_122504.jpg",
  905. "size" : 8406507,
  906. "type" : "FILE_INFO_TYPE_FILE"
  907. },
  908. {
  909. "modTime" : "2020\-12\-13T12:25:06.127097469+01:00",
  910. "name" : "IMG_20201213_122505.jpg",
  911. "size" : 8381931,
  912. "type" : "FILE_INFO_TYPE_FILE"
  913. },
  914. {
  915. "modTime" : "2020\-12\-13T12:53:29.707298401+01:00",
  916. "name" : "IMG_20201213_125329.jpg",
  917. "size" : 4388331,
  918. "type" : "FILE_INFO_TYPE_FILE"
  919. },
  920. ],
  921. "modTime" : "2020\-10\-09T13:04:42.4410738+02:00",
  922. "name" : "Camera",
  923. "size" : 128,
  924. "type" : "FILE_INFO_TYPE_DIRECTORY"
  925. },
  926. ]
  927. .ft P
  928. .fi
  929. .UNINDENT
  930. .UNINDENT
  931. .sp
  932. \fBNOTE:\fP
  933. .INDENT 0.0
  934. .INDENT 3.5
  935. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  936. .UNINDENT
  937. .UNINDENT
  938. .SS GET /rest/db/completion
  939. .sp
  940. Returns the completion percentage (0 to 100) and byte / item counts. Takes
  941. optional \fBdevice\fP and \fBfolder\fP parameters:
  942. .INDENT 0.0
  943. .IP \(bu 2
  944. \fBfolder\fP specifies the folder ID to calculate completion for. An empty
  945. or absent \fBfolder\fP parameter means all folders as an aggregate.
  946. .IP \(bu 2
  947. \fBdevice\fP specifies the device ID to calculate completion for. An empty
  948. or absent \fBdevice\fP parameter means the local device.
  949. .UNINDENT
  950. .sp
  951. If a device is specified but no folder, completion is calculated for all
  952. folders shared with that device.
  953. .SS Example Queries
  954. .sp
  955. Completion status for folder \fBabcd\-1234\fP on device \fBI6KAH76\-...\-3PSROAU\fP:
  956. .INDENT 0.0
  957. .INDENT 3.5
  958. .sp
  959. .nf
  960. .ft C
  961. /rest/db/completion?folder=abcd\-1234&device=I6KAH76\-...\-3PSROAU
  962. .ft P
  963. .fi
  964. .UNINDENT
  965. .UNINDENT
  966. .sp
  967. Aggregated completion status for device \fBI6KAH76\-...\-3PSROAU\fP (all folders shared with them):
  968. .INDENT 0.0
  969. .INDENT 3.5
  970. .sp
  971. .nf
  972. .ft C
  973. /rest/db/completion?device=I6KAH76\-...\-3PSROAU
  974. .ft P
  975. .fi
  976. .UNINDENT
  977. .UNINDENT
  978. .sp
  979. Completion status for folder \fBabcd\-1234\fP on the local device:
  980. .INDENT 0.0
  981. .INDENT 3.5
  982. .sp
  983. .nf
  984. .ft C
  985. /rest/db/completion?folder=abcd\-1234
  986. .ft P
  987. .fi
  988. .UNINDENT
  989. .UNINDENT
  990. .sp
  991. Aggregated completion status for all folders on the local device:
  992. .INDENT 0.0
  993. .INDENT 3.5
  994. .sp
  995. .nf
  996. .ft C
  997. /rest/db/completion
  998. .ft P
  999. .fi
  1000. .UNINDENT
  1001. .UNINDENT
  1002. .SS Example Response
  1003. .INDENT 0.0
  1004. .INDENT 3.5
  1005. .sp
  1006. .nf
  1007. .ft C
  1008. {
  1009. "completion": 99.9937565835,
  1010. "globalBytes": 156793013575,
  1011. "needBytes": 9789241,
  1012. "globalItems": 7823,
  1013. "needItems": 412,
  1014. "needDeletes": 0
  1015. }
  1016. .ft P
  1017. .fi
  1018. .UNINDENT
  1019. .UNINDENT
  1020. .sp
  1021. New in version 1.8.0: The ability to aggregate multiple folders by leaving out the folder ID.
  1022. Querying data for the local device by leaving out the device ID. Returning
  1023. the \fBglobalItems\fP counter in the response.
  1024. .SS GET /rest/db/file
  1025. .sp
  1026. Returns most data available about a given file, including version and
  1027. availability. Takes \fBfolder\fP and \fBfile\fP parameters.
  1028. .INDENT 0.0
  1029. .INDENT 3.5
  1030. .sp
  1031. .nf
  1032. .ft C
  1033. {
  1034. "availability": [
  1035. {
  1036. "id": "ITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM",
  1037. "fromTemporary": false
  1038. }
  1039. ],
  1040. "global": {
  1041. "deleted": false,
  1042. "ignored": false,
  1043. "invalid": false,
  1044. "localFlags": 0,
  1045. "modified": "2018\-08\-18T12:21:13.836784059+02:00",
  1046. "modifiedBy": "SYNO4VL",
  1047. "mustRescan": false,
  1048. "name": "testfile",
  1049. "noPermissions": false,
  1050. "numBlocks": 1,
  1051. "permissions": "0755",
  1052. "sequence": 107499,
  1053. "size": 1234,
  1054. "type": 0,
  1055. "version": [
  1056. "SYNO4VL:1"
  1057. ]
  1058. },
  1059. "local": {
  1060. "deleted": false,
  1061. "ignored": false,
  1062. "invalid": false,
  1063. "localFlags": 0,
  1064. "modified": "2018\-08\-18T12:21:13.836784059+02:00",
  1065. "modifiedBy": "SYNO4VL",
  1066. "mustRescan": false,
  1067. "name": "testfile",
  1068. "noPermissions": false,
  1069. "numBlocks": 1,
  1070. "permissions": "0755",
  1071. "sequence": 111038,
  1072. "size": 1234,
  1073. "type": 0,
  1074. "version": [
  1075. "SYNO4VL:1"
  1076. ]
  1077. }
  1078. }
  1079. .ft P
  1080. .fi
  1081. .UNINDENT
  1082. .UNINDENT
  1083. .SS GET /rest/db/ignores
  1084. .sp
  1085. Takes one parameter, \fBfolder\fP, and returns the content of the
  1086. \fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBexpanded\fP,
  1087. 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.
  1088. .INDENT 0.0
  1089. .INDENT 3.5
  1090. .sp
  1091. .nf
  1092. .ft C
  1093. {
  1094. "ignore": [
  1095. "(?i)/Backups"
  1096. ],
  1097. "expanded": [
  1098. "(?i)Backups",
  1099. "(?i)Backups/**"
  1100. ]
  1101. }
  1102. .ft P
  1103. .fi
  1104. .UNINDENT
  1105. .UNINDENT
  1106. .SS POST /rest/db/ignores
  1107. .sp
  1108. Expects a format similar to the output of \fBGET\fP call, but only
  1109. containing the \fBignore\fP field (\fBexpanded\fP field should be omitted).
  1110. It takes one parameter, \fBfolder\fP, and either updates the content of
  1111. the \fB\&.stignore\fP echoing it back as a response, or returns an error.
  1112. .SS GET /rest/db/need
  1113. .sp
  1114. Takes one mandatory parameter, \fBfolder\fP, and returns lists of files which are
  1115. needed by this device in order for it to become in sync.
  1116. .sp
  1117. Furthermore takes an optional \fBpage\fP and \fBperpage\fP arguments for pagination.
  1118. Pagination happens, across the union of all needed files, that is \- across all
  1119. 3 sections of the response.
  1120. For example, given the current need state is as follows:
  1121. .INDENT 0.0
  1122. .IP 1. 3
  1123. \fBprogress\fP has 15 items
  1124. .IP 2. 3
  1125. \fBqueued\fP has 3 items
  1126. .IP 3. 3
  1127. \fBrest\fP has 12 items
  1128. .UNINDENT
  1129. .sp
  1130. If you issue a query with \fBpage=1\fP and \fBperpage=10\fP, only the \fBprogress\fP
  1131. section in the response will have 10 items. If you issue a request query with
  1132. \fBpage=2\fP and \fBperpage=10\fP, \fBprogress\fP section will have the last 5 items,
  1133. \fBqueued\fP section will have all 3 items, and \fBrest\fP section will have first
  1134. 2 items. If you issue a query for \fBpage=3\fP and \fBperpage=10\fP, you will only
  1135. have the last 10 items of the \fBrest\fP section.
  1136. .sp
  1137. In all these calls, \fBtotal\fP will be 30 to indicate the total number of
  1138. available items.
  1139. .INDENT 0.0
  1140. .INDENT 3.5
  1141. .sp
  1142. .nf
  1143. .ft C
  1144. {
  1145. # Files currently being downloaded
  1146. "progress": [
  1147. {
  1148. "flags": "0755",
  1149. "sequence": 6,
  1150. "modified": "2015\-04\-20T23:06:12+09:00",
  1151. "name": "ls",
  1152. "size": 34640,
  1153. "version": [
  1154. "5157751870738175669:1"
  1155. ]
  1156. }
  1157. ],
  1158. # Files queued to be downloaded next (as per array order)
  1159. "queued": [
  1160. ...
  1161. ],
  1162. # Files to be downloaded after all queued files will be downloaded.
  1163. # This happens when we start downloading files, and new files get added while we are downloading.
  1164. "rest": [
  1165. ...
  1166. ],
  1167. "page": 1,
  1168. "perpage": 100,
  1169. "total": 2000
  1170. }
  1171. .ft P
  1172. .fi
  1173. .UNINDENT
  1174. .UNINDENT
  1175. .sp
  1176. \fBNOTE:\fP
  1177. .INDENT 0.0
  1178. .INDENT 3.5
  1179. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  1180. .UNINDENT
  1181. .UNINDENT
  1182. .SS POST /rest/db/override
  1183. .sp
  1184. Request override of a send only folder. Override means to make the local
  1185. version latest, overriding changes made on other devices. This API call does
  1186. nothing if the folder is not a send only folder.
  1187. .sp
  1188. Takes the mandatory parameter \fIfolder\fP (folder ID).
  1189. .INDENT 0.0
  1190. .INDENT 3.5
  1191. .sp
  1192. .nf
  1193. .ft C
  1194. curl \-X POST \-H X\-API\-key:... http://127.0.0.1:8384/rest/db/override?folder=default
  1195. .ft P
  1196. .fi
  1197. .UNINDENT
  1198. .UNINDENT
  1199. .SS POST /rest/db/prio
  1200. .sp
  1201. Moves the file to the top of the download queue.
  1202. .INDENT 0.0
  1203. .INDENT 3.5
  1204. .sp
  1205. .nf
  1206. .ft C
  1207. curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
  1208. .ft P
  1209. .fi
  1210. .UNINDENT
  1211. .UNINDENT
  1212. .sp
  1213. Response contains the same output as \fBGET /rest/db/need\fP
  1214. .SS POST /rest/db/revert
  1215. .sp
  1216. New in version 0.14.50.
  1217. .sp
  1218. Request revert of a receive only folder. Reverting a folder means to undo
  1219. all local changes. This API call does nothing if the folder is not a receive
  1220. only folder.
  1221. .sp
  1222. Takes the mandatory parameter \fIfolder\fP (folder ID).
  1223. .INDENT 0.0
  1224. .INDENT 3.5
  1225. .sp
  1226. .nf
  1227. .ft C
  1228. curl \-X POST \-H X\-API\-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
  1229. .ft P
  1230. .fi
  1231. .UNINDENT
  1232. .UNINDENT
  1233. .SS POST /rest/db/scan
  1234. .sp
  1235. Request immediate scan. Takes the optional parameters \fBfolder\fP (folder ID),
  1236. \fBsub\fP (path relative to the folder root) and \fBnext\fP (time in seconds). If
  1237. \fBfolder\fP is omitted or empty all folders are scanned. If \fBsub\fP is given,
  1238. only this path (and children, in case it’s a directory) is scanned. The \fBnext\fP
  1239. argument delays Syncthing’s automated rescan interval for a given amount of
  1240. seconds.
  1241. .sp
  1242. Requesting scan of a path that no longer exists, but previously did, is
  1243. valid and will result in Syncthing noticing the deletion of the path in
  1244. question.
  1245. .sp
  1246. Returns status 200 and no content upon success, or status 500 and a
  1247. plain text error if an error occurred during scanning.
  1248. .INDENT 0.0
  1249. .INDENT 3.5
  1250. .sp
  1251. .nf
  1252. .ft C
  1253. curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
  1254. .ft P
  1255. .fi
  1256. .UNINDENT
  1257. .UNINDENT
  1258. .SS GET /rest/db/status
  1259. .sp
  1260. Returns information about the current status of a folder.
  1261. .sp
  1262. Parameters: \fBfolder\fP, the ID of a folder.
  1263. .INDENT 0.0
  1264. .INDENT 3.5
  1265. .sp
  1266. .nf
  1267. .ft C
  1268. {
  1269. "globalBytes": 0,
  1270. "globalDeleted": 0,
  1271. "globalDirectories": 0,
  1272. "globalFiles": 0,
  1273. "globalSymlinks": 0,
  1274. "globalTotalItems": 0,
  1275. "ignorePatterns": false,
  1276. "inSyncBytes": 0,
  1277. "inSyncFiles": 0,
  1278. "invalid": "",
  1279. "localBytes": 0,
  1280. "localDeleted": 0,
  1281. "localDirectories": 0,
  1282. "localFiles": 0,
  1283. "localSymlinks": 0,
  1284. "localTotalItems": 0,
  1285. "needBytes": 0,
  1286. "needDeletes": 0,
  1287. "needDirectories": 0,
  1288. "needFiles": 0,
  1289. "needSymlinks": 0,
  1290. "needTotalItems": 0,
  1291. "pullErrors": 0,
  1292. "receiveOnlyChangedBytes": 0,
  1293. "receiveOnlyChangedDeletes": 0,
  1294. "receiveOnlyChangedDirectories": 0,
  1295. "receiveOnlyChangedFiles": 0,
  1296. "receiveOnlyChangedSymlinks": 0,
  1297. "receiveOnlyTotalItems": 0,
  1298. "sequence": 0,
  1299. "state": "idle",
  1300. "stateChanged": "2018\-08\-08T07:04:57.301064781+02:00",
  1301. "version": 0
  1302. }
  1303. .ft P
  1304. .fi
  1305. .UNINDENT
  1306. .UNINDENT
  1307. .sp
  1308. The various fields have the following meaning:
  1309. .INDENT 0.0
  1310. .TP
  1311. .B global*:
  1312. Data in the cluster latest version.
  1313. .TP
  1314. .B inSync*:
  1315. Data that is locally the same as the cluster latest version.
  1316. .TP
  1317. .B local*:
  1318. Data that is locally present, regardless of whether it’s the same or different version as the cluster latest version.
  1319. .TP
  1320. .B need*:
  1321. Data that is needed to become up to date with the cluster latest version (i.e., data that is out of sync).
  1322. .TP
  1323. .B receiveOnlyChanged*:
  1324. Data that has changed locally in a receive only folder, and thus not been sent to the cluster.
  1325. .TP
  1326. .B invalid:
  1327. Deprecated, always empty.
  1328. .TP
  1329. .B pullErrors:
  1330. The number of files that failed to sync during the last sync operations.
  1331. .TP
  1332. .B sequence:
  1333. The current folder sequence number.
  1334. .TP
  1335. .B state:
  1336. The current folder state.
  1337. .TP
  1338. .B stateChanged:
  1339. When the folder state last changed.
  1340. .TP
  1341. .B version:
  1342. Deprecated, equivalent to the sequence number.
  1343. .UNINDENT
  1344. .sp
  1345. \fBNOTE:\fP
  1346. .INDENT 0.0
  1347. .INDENT 3.5
  1348. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  1349. .UNINDENT
  1350. .UNINDENT
  1351. .SH EVENT ENDPOINTS
  1352. .SS GET /rest/events
  1353. .sp
  1354. To receive events, perform a HTTP GET of \fB/rest/events\fP\&.
  1355. .sp
  1356. To filter the event list, in effect creating a specific subscription for
  1357. only the desired event types, add a parameter
  1358. \fBevents=EventTypeA,EventTypeB,...\fP where the event types are any of the event\-types\&.
  1359. .sp
  1360. The optional parameter \fBsince=<lastSeenID>\fP sets the ID of the last event
  1361. you’ve already seen. Syncthing returns a JSON encoded array of event objects,
  1362. starting at the event just after the one with this last seen ID. The default
  1363. value is 0, which returns all events. There is a limit to the number of events
  1364. buffered, so if the rate of events is high or the time between polling calls is
  1365. long some events might be missed. This can be detected by noting a discontinuity
  1366. in the event IDs.
  1367. .sp
  1368. If no new events are produced since \fB<lastSeenID>\fP, the HTTP call blocks and
  1369. waits for new events to happen before returning. By default it times out after
  1370. 60 seconds returning an empty array. The time out duration can be customized
  1371. with the optional parameter \fBtimeout=<seconds>\fP\&.
  1372. .sp
  1373. To receive only a limited number of events, add the \fBlimit=<n>\fP parameter with a
  1374. suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This
  1375. can be used to catch up with the latest event ID after a disconnection for
  1376. example: \fB/rest/events?since=0&limit=1\fP\&.
  1377. .SH STATISTICS ENDPOINTS
  1378. .SS GET /rest/stats/device
  1379. .sp
  1380. Returns general statistics about devices. Currently, only contains the
  1381. time the device was last seen.
  1382. .INDENT 0.0
  1383. .INDENT 3.5
  1384. .sp
  1385. .nf
  1386. .ft C
  1387. $ curl \-s http://localhost:8384/rest/stats/device | json
  1388. {
  1389. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  1390. "lastSeen" : "2015\-04\-18T11:21:31.3256277+01:00"
  1391. }
  1392. }
  1393. .ft P
  1394. .fi
  1395. .UNINDENT
  1396. .UNINDENT
  1397. .SS GET /rest/stats/folder
  1398. .sp
  1399. Returns general statistics about folders. Currently contains the
  1400. last scan time and the last synced file.
  1401. .INDENT 0.0
  1402. .INDENT 3.5
  1403. .sp
  1404. .nf
  1405. .ft C
  1406. $ curl \-s http://localhost:8384/rest/stats/folder | json
  1407. {
  1408. "folderid" : {
  1409. "lastScan": "2016\-06\-02T13:28:01.288181412\-04:00",
  1410. "lastFile" : {
  1411. "filename" : "file/name",
  1412. "at" : "2015\-04\-16T22:04:18.3066971+01:00"
  1413. }
  1414. }
  1415. }
  1416. .ft P
  1417. .fi
  1418. .UNINDENT
  1419. .UNINDENT
  1420. .SH MISC SERVICES ENDPOINTS
  1421. .SS GET /rest/svc/deviceid
  1422. .sp
  1423. Verifies and formats a device ID. Accepts all currently valid formats
  1424. (52 or 56 characters with or without separators, upper or lower case,
  1425. with trivial substitutions). Takes one parameter, \fBid\fP, and returns
  1426. either a valid device ID in modern format, or an error.
  1427. .INDENT 0.0
  1428. .INDENT 3.5
  1429. .sp
  1430. .nf
  1431. .ft C
  1432. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json
  1433. {
  1434. "error": "device ID invalid: incorrect length"
  1435. }
  1436. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
  1437. {
  1438. "id": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2"
  1439. }
  1440. .ft P
  1441. .fi
  1442. .UNINDENT
  1443. .UNINDENT
  1444. .SS GET /rest/svc/lang
  1445. .sp
  1446. Returns a list of canonicalized localization codes, as picked up from
  1447. the \fBAccept\-Language\fP header sent by the browser.
  1448. .INDENT 0.0
  1449. .INDENT 3.5
  1450. .sp
  1451. .nf
  1452. .ft C
  1453. ["sv_sv","sv","en_us","en"]
  1454. .ft P
  1455. .fi
  1456. .UNINDENT
  1457. .UNINDENT
  1458. .SS GET /rest/svc/random/string
  1459. .sp
  1460. Returns a strong random generated string (alphanumeric) of the specified length. Takes the \fBlength\fP parameter.
  1461. .INDENT 0.0
  1462. .INDENT 3.5
  1463. .sp
  1464. .nf
  1465. .ft C
  1466. {
  1467. "random": "FdPaEaZQ56sXEKYNxpgF"
  1468. }
  1469. .ft P
  1470. .fi
  1471. .UNINDENT
  1472. .UNINDENT
  1473. .SS GET /rest/svc/report
  1474. .sp
  1475. Returns the data sent in the anonymous usage report.
  1476. .INDENT 0.0
  1477. .INDENT 3.5
  1478. .sp
  1479. .nf
  1480. .ft C
  1481. {
  1482. "folderMaxMiB" : 0,
  1483. "platform" : "linux\-amd64",
  1484. "totMiB" : 0,
  1485. "longVersion" : "syncthing v0.12.2 \e"Beryllium Bedbug\e" (go1.4.3 linux\-amd64 default) unknown\[email protected] 2015\-11\-09 13:23:26 UTC",
  1486. "upgradeAllowedManual" : true,
  1487. "totFiles" : 3,
  1488. "folderUses" : {
  1489. "ignorePerms" : 0,
  1490. "autoNormalize" : 0,
  1491. "sendonly" : 0,
  1492. "ignoreDelete" : 0
  1493. },
  1494. "memoryUsageMiB" : 13,
  1495. "version" : "v0.12.2",
  1496. "sha256Perf" : 27.28,
  1497. "numFolders" : 2,
  1498. "memorySize" : 1992,
  1499. "announce" : {
  1500. "defaultServersIP" : 0,
  1501. "otherServers" : 0,
  1502. "globalEnabled" : false,
  1503. "defaultServersDNS" : 1,
  1504. "localEnabled" : false
  1505. },
  1506. "usesRateLimit" : false,
  1507. "numCPU" : 2,
  1508. "uniqueID" : "",
  1509. "urVersion" : 2,
  1510. "rescanIntvs" : [
  1511. 60,
  1512. 60
  1513. ],
  1514. "numDevices" : 2,
  1515. "folderMaxFiles" : 3,
  1516. "relays" : {
  1517. "defaultServers" : 1,
  1518. "enabled" : true,
  1519. "otherServers" : 0
  1520. },
  1521. "deviceUses" : {
  1522. "compressMetadata" : 1,
  1523. "customCertName" : 0,
  1524. "staticAddr" : 1,
  1525. "compressAlways" : 0,
  1526. "compressNever" : 1,
  1527. "introducer" : 0,
  1528. "dynamicAddr" : 1
  1529. },
  1530. "upgradeAllowedAuto" : false
  1531. }
  1532. .ft P
  1533. .fi
  1534. .UNINDENT
  1535. .UNINDENT
  1536. .SH AUTHOR
  1537. The Syncthing Authors
  1538. .SH COPYRIGHT
  1539. 2014-2019, The Syncthing Authors
  1540. .\" Generated by docutils manpage writer.
  1541. .