syncthing-rest-api.7 42 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566
  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" "Oct 17, 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=ab1c2\-def3g
  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. \fBPATCH\fP replaces only the given child objects and \fBDELETE\fP removes the
  743. folder/device.
  744. .SS /rest/config/options, /rest/config/ldap, /rest/config/gui
  745. .sp
  746. \fBGET\fP returns the respective object, \fBPUT\fP replaces the entire object and
  747. \fBPATCH\fP replaces only the given child objects.
  748. .SH CLUSTER ENDPOINTS
  749. .sp
  750. Concerns the mesh network structure.
  751. .SS DELETE /rest/cluster/pending/devices
  752. .sp
  753. New in version 1.18.0.
  754. .sp
  755. Remove records about a pending remote device which tried to connect.
  756. Valid values for the \fBdevice\fP parameter are those from the
  757. corresponding /rest/cluster\-pending\-devices\-get endpoint.
  758. .INDENT 0.0
  759. .INDENT 3.5
  760. .sp
  761. .nf
  762. .ft C
  763. $ curl \-X DELETE \-H "X\-API\-Key: abc123" http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
  764. .ft P
  765. .fi
  766. .UNINDENT
  767. .UNINDENT
  768. .sp
  769. Returns status 200 and no content upon success, or status 500 and a
  770. plain text error on failure. A /events/pendingdeviceschanged
  771. event will be generated in response.
  772. .sp
  773. For a more permanent effect, also for future connections from the same
  774. device ID, the device should be ignored in the configuration instead.
  775. .SS GET /rest/cluster/pending/devices
  776. .sp
  777. New in version 1.13.0.
  778. .sp
  779. Lists remote devices which have tried to connect, but are not yet
  780. configured in our instance.
  781. .INDENT 0.0
  782. .INDENT 3.5
  783. .sp
  784. .nf
  785. .ft C
  786. {
  787. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  788. "time": "2020\-03\-18T11:43:07Z",
  789. "name": "Friend Joe",
  790. "address": "192.168.1.2:22000"
  791. }
  792. }
  793. .ft P
  794. .fi
  795. .UNINDENT
  796. .UNINDENT
  797. .SS DELETE /rest/cluster/pending/folders
  798. .sp
  799. New in version 1.18.0.
  800. .sp
  801. Remove records about a pending folder announced from a remote device.
  802. Valid values for the \fBfolder\fP and \fBdevice\fP parameters are those
  803. from the corresponding /rest/cluster\-pending\-folders\-get
  804. endpoint. The \fBdevice\fP parameter is optional and affects
  805. announcements of this folder from the given device, or from \fIany\fP
  806. device if omitted.
  807. .INDENT 0.0
  808. .INDENT 3.5
  809. .sp
  810. .nf
  811. .ft C
  812. $ 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
  813. .ft P
  814. .fi
  815. .UNINDENT
  816. .UNINDENT
  817. .sp
  818. Returns status 200 and no content upon success, or status 500 and a
  819. plain text error on failure. A /events/pendingfolderschanged
  820. event will be generated in response.
  821. .sp
  822. For a more permanent effect, also for future announcements of the same
  823. folder ID, the folder should be ignored in the configuration instead.
  824. .SS GET /rest/cluster/pending/folders
  825. .sp
  826. New in version 1.13.0.
  827. .sp
  828. Lists folders which remote devices have offered to us, but are not yet
  829. shared from our instance to them. Takes the optional \fBdevice\fP
  830. parameter to only return folders offered by a specific remote device.
  831. Other offering devices are also omitted from the result.
  832. .INDENT 0.0
  833. .INDENT 3.5
  834. .sp
  835. .nf
  836. .ft C
  837. {
  838. "cpkn4\-57ysy": {
  839. "offeredBy": {
  840. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  841. "time": "2020\-03\-18T11:43:07Z",
  842. "label": "Joe\(aqs folder",
  843. "receiveEncrypted": true,
  844. "remoteEncrypted": false
  845. },
  846. "DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA": {
  847. "time": "2020\-03\-01T10:12:13Z",
  848. "label": "Jane\(aqs and Joe\(aqs folder",
  849. "receiveEncrypted": false,
  850. "remoteEncrypted": false
  851. }
  852. }
  853. },
  854. "abcde\-fghij": {
  855. "offeredBy": {
  856. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  857. "time": "2020\-03\-18T11:43:07Z",
  858. "label": "MyPics",
  859. "receiveEncrypted": false,
  860. "remoteEncrypted": false
  861. }
  862. }
  863. }
  864. }
  865. .ft P
  866. .fi
  867. .UNINDENT
  868. .UNINDENT
  869. .SH DATABASE ENDPOINTS
  870. .SS GET /rest/db/browse
  871. .sp
  872. Returns the directory tree of the global model. Directories are always
  873. JSON objects (map/dictionary), and files are always arrays of
  874. modification time and size. The first integer is the files modification
  875. time, and the second integer is the file size.
  876. .sp
  877. The call takes one mandatory \fBfolder\fP parameter and two optional
  878. parameters. Optional parameter \fBlevels\fP defines how deep within the
  879. tree we want to dwell down (0 based, defaults to unlimited depth)
  880. Optional parameter \fBprefix\fP defines a prefix within the tree where to
  881. start building the structure.
  882. .INDENT 0.0
  883. .INDENT 3.5
  884. .sp
  885. .nf
  886. .ft C
  887. $ curl \-s http://localhost:8384/rest/db/browse?folder=j663y\-3ct3e&prefix=DCIM&levels=2
  888. [
  889. {
  890. "modTime" : "2020\-10\-02T23:48:52.076996974+02:00",
  891. "name" : "100ANDRO",
  892. "size" : 128,
  893. "type" : "FILE_INFO_TYPE_DIRECTORY"
  894. },
  895. {
  896. "children" : [
  897. {
  898. "modTime" : "2020\-12\-16T23:31:34.5009668+01:00",
  899. "name" : "IMG_20201114_124821.jpg",
  900. "size" : 10682189,
  901. "type" : "FILE_INFO_TYPE_FILE"
  902. },
  903. {
  904. "modTime" : "2020\-12\-16T23:31:35.0106367+01:00",
  905. "name" : "IMG_20201213_122451.jpg",
  906. "size" : 7936351,
  907. "type" : "FILE_INFO_TYPE_FILE"
  908. },
  909. {
  910. "modTime" : "2020\-12\-13T12:25:05.017097469+01:00",
  911. "name" : "IMG_20201213_122504.jpg",
  912. "size" : 8406507,
  913. "type" : "FILE_INFO_TYPE_FILE"
  914. },
  915. {
  916. "modTime" : "2020\-12\-13T12:25:06.127097469+01:00",
  917. "name" : "IMG_20201213_122505.jpg",
  918. "size" : 8381931,
  919. "type" : "FILE_INFO_TYPE_FILE"
  920. },
  921. {
  922. "modTime" : "2020\-12\-13T12:53:29.707298401+01:00",
  923. "name" : "IMG_20201213_125329.jpg",
  924. "size" : 4388331,
  925. "type" : "FILE_INFO_TYPE_FILE"
  926. },
  927. ],
  928. "modTime" : "2020\-10\-09T13:04:42.4410738+02:00",
  929. "name" : "Camera",
  930. "size" : 128,
  931. "type" : "FILE_INFO_TYPE_DIRECTORY"
  932. },
  933. ]
  934. .ft P
  935. .fi
  936. .UNINDENT
  937. .UNINDENT
  938. .sp
  939. \fBNOTE:\fP
  940. .INDENT 0.0
  941. .INDENT 3.5
  942. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  943. .UNINDENT
  944. .UNINDENT
  945. .SS GET /rest/db/completion
  946. .sp
  947. Returns the completion percentage (0 to 100) and byte / item counts. Takes
  948. optional \fBdevice\fP and \fBfolder\fP parameters:
  949. .INDENT 0.0
  950. .IP \(bu 2
  951. \fBfolder\fP specifies the folder ID to calculate completion for. An empty
  952. or absent \fBfolder\fP parameter means all folders as an aggregate.
  953. .IP \(bu 2
  954. \fBdevice\fP specifies the device ID to calculate completion for. An empty
  955. or absent \fBdevice\fP parameter means the local device.
  956. .UNINDENT
  957. .sp
  958. If a device is specified but no folder, completion is calculated for all
  959. folders shared with that device.
  960. .SS Example Queries
  961. .sp
  962. Completion status for folder \fBabcd\-1234\fP on device \fBI6KAH76\-...\-3PSROAU\fP:
  963. .INDENT 0.0
  964. .INDENT 3.5
  965. .sp
  966. .nf
  967. .ft C
  968. /rest/db/completion?folder=abcd\-1234&device=I6KAH76\-...\-3PSROAU
  969. .ft P
  970. .fi
  971. .UNINDENT
  972. .UNINDENT
  973. .sp
  974. Aggregated completion status for device \fBI6KAH76\-...\-3PSROAU\fP (all folders shared with them):
  975. .INDENT 0.0
  976. .INDENT 3.5
  977. .sp
  978. .nf
  979. .ft C
  980. /rest/db/completion?device=I6KAH76\-...\-3PSROAU
  981. .ft P
  982. .fi
  983. .UNINDENT
  984. .UNINDENT
  985. .sp
  986. Completion status for folder \fBabcd\-1234\fP on the local device:
  987. .INDENT 0.0
  988. .INDENT 3.5
  989. .sp
  990. .nf
  991. .ft C
  992. /rest/db/completion?folder=abcd\-1234
  993. .ft P
  994. .fi
  995. .UNINDENT
  996. .UNINDENT
  997. .sp
  998. Aggregated completion status for all folders on the local device:
  999. .INDENT 0.0
  1000. .INDENT 3.5
  1001. .sp
  1002. .nf
  1003. .ft C
  1004. /rest/db/completion
  1005. .ft P
  1006. .fi
  1007. .UNINDENT
  1008. .UNINDENT
  1009. .SS Example Response
  1010. .INDENT 0.0
  1011. .INDENT 3.5
  1012. .sp
  1013. .nf
  1014. .ft C
  1015. {
  1016. "completion": 99.9937565835,
  1017. "globalBytes": 156793013575,
  1018. "needBytes": 9789241,
  1019. "globalItems": 7823,
  1020. "needItems": 412,
  1021. "needDeletes": 0
  1022. }
  1023. .ft P
  1024. .fi
  1025. .UNINDENT
  1026. .UNINDENT
  1027. .sp
  1028. New in version 1.8.0: The ability to aggregate multiple folders by leaving out the folder ID.
  1029. Querying data for the local device by leaving out the device ID. Returning
  1030. the \fBglobalItems\fP counter in the response.
  1031. .SS GET /rest/db/file
  1032. .sp
  1033. Returns most data available about a given file, including version and
  1034. availability. Takes \fBfolder\fP and \fBfile\fP parameters.
  1035. .INDENT 0.0
  1036. .INDENT 3.5
  1037. .sp
  1038. .nf
  1039. .ft C
  1040. {
  1041. "availability": [
  1042. {
  1043. "id": "ITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM",
  1044. "fromTemporary": false
  1045. }
  1046. ],
  1047. "global": {
  1048. "deleted": false,
  1049. "ignored": false,
  1050. "invalid": false,
  1051. "localFlags": 0,
  1052. "modified": "2018\-08\-18T12:21:13.836784059+02:00",
  1053. "modifiedBy": "SYNO4VL",
  1054. "mustRescan": false,
  1055. "name": "testfile",
  1056. "noPermissions": false,
  1057. "numBlocks": 1,
  1058. "permissions": "0755",
  1059. "sequence": 107499,
  1060. "size": 1234,
  1061. "type": 0,
  1062. "version": [
  1063. "SYNO4VL:1"
  1064. ]
  1065. },
  1066. "local": {
  1067. "deleted": false,
  1068. "ignored": false,
  1069. "invalid": false,
  1070. "localFlags": 0,
  1071. "modified": "2018\-08\-18T12:21:13.836784059+02:00",
  1072. "modifiedBy": "SYNO4VL",
  1073. "mustRescan": false,
  1074. "name": "testfile",
  1075. "noPermissions": false,
  1076. "numBlocks": 1,
  1077. "permissions": "0755",
  1078. "sequence": 111038,
  1079. "size": 1234,
  1080. "type": 0,
  1081. "version": [
  1082. "SYNO4VL:1"
  1083. ]
  1084. }
  1085. }
  1086. .ft P
  1087. .fi
  1088. .UNINDENT
  1089. .UNINDENT
  1090. .SS GET /rest/db/ignores
  1091. .sp
  1092. Takes one parameter, \fBfolder\fP, and returns the content of the
  1093. \fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBexpanded\fP,
  1094. 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.
  1095. .INDENT 0.0
  1096. .INDENT 3.5
  1097. .sp
  1098. .nf
  1099. .ft C
  1100. {
  1101. "ignore": [
  1102. "(?i)/Backups"
  1103. ],
  1104. "expanded": [
  1105. "(?i)Backups",
  1106. "(?i)Backups/**"
  1107. ]
  1108. }
  1109. .ft P
  1110. .fi
  1111. .UNINDENT
  1112. .UNINDENT
  1113. .SS POST /rest/db/ignores
  1114. .sp
  1115. Expects a format similar to the output of \fBGET\fP call, but only
  1116. containing the \fBignore\fP field (\fBexpanded\fP field should be omitted).
  1117. It takes one parameter, \fBfolder\fP, and either updates the content of
  1118. the \fB\&.stignore\fP echoing it back as a response, or returns an error.
  1119. .SS GET /rest/db/need
  1120. .sp
  1121. Takes one mandatory parameter, \fBfolder\fP, and returns lists of files which are
  1122. needed by this device in order for it to become in sync.
  1123. .sp
  1124. Furthermore takes an optional \fBpage\fP and \fBperpage\fP arguments for pagination.
  1125. Pagination happens, across the union of all needed files, that is \- across all
  1126. 3 sections of the response.
  1127. For example, given the current need state is as follows:
  1128. .INDENT 0.0
  1129. .IP 1. 3
  1130. \fBprogress\fP has 15 items
  1131. .IP 2. 3
  1132. \fBqueued\fP has 3 items
  1133. .IP 3. 3
  1134. \fBrest\fP has 12 items
  1135. .UNINDENT
  1136. .sp
  1137. If you issue a query with \fBpage=1\fP and \fBperpage=10\fP, only the \fBprogress\fP
  1138. section in the response will have 10 items. If you issue a request query with
  1139. \fBpage=2\fP and \fBperpage=10\fP, \fBprogress\fP section will have the last 5 items,
  1140. \fBqueued\fP section will have all 3 items, and \fBrest\fP section will have first
  1141. 2 items. If you issue a query for \fBpage=3\fP and \fBperpage=10\fP, you will only
  1142. have the last 10 items of the \fBrest\fP section.
  1143. .sp
  1144. In all these calls, \fBtotal\fP will be 30 to indicate the total number of
  1145. available items.
  1146. .INDENT 0.0
  1147. .INDENT 3.5
  1148. .sp
  1149. .nf
  1150. .ft C
  1151. {
  1152. # Files currently being downloaded
  1153. "progress": [
  1154. {
  1155. "flags": "0755",
  1156. "sequence": 6,
  1157. "modified": "2015\-04\-20T23:06:12+09:00",
  1158. "name": "ls",
  1159. "size": 34640,
  1160. "version": [
  1161. "5157751870738175669:1"
  1162. ]
  1163. }
  1164. ],
  1165. # Files queued to be downloaded next (as per array order)
  1166. "queued": [
  1167. ...
  1168. ],
  1169. # Files to be downloaded after all queued files will be downloaded.
  1170. # This happens when we start downloading files, and new files get added while we are downloading.
  1171. "rest": [
  1172. ...
  1173. ],
  1174. "page": 1,
  1175. "perpage": 100,
  1176. "total": 2000
  1177. }
  1178. .ft P
  1179. .fi
  1180. .UNINDENT
  1181. .UNINDENT
  1182. .sp
  1183. \fBNOTE:\fP
  1184. .INDENT 0.0
  1185. .INDENT 3.5
  1186. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  1187. .UNINDENT
  1188. .UNINDENT
  1189. .SS POST /rest/db/override
  1190. .sp
  1191. Request override of a send only folder. Override means to make the local
  1192. version latest, overriding changes made on other devices. This API call does
  1193. nothing if the folder is not a send only folder.
  1194. .sp
  1195. Takes the mandatory parameter \fIfolder\fP (folder ID).
  1196. .INDENT 0.0
  1197. .INDENT 3.5
  1198. .sp
  1199. .nf
  1200. .ft C
  1201. curl \-X POST \-H X\-API\-key:... http://127.0.0.1:8384/rest/db/override?folder=default
  1202. .ft P
  1203. .fi
  1204. .UNINDENT
  1205. .UNINDENT
  1206. .SS POST /rest/db/prio
  1207. .sp
  1208. Moves the file to the top of the download queue.
  1209. .INDENT 0.0
  1210. .INDENT 3.5
  1211. .sp
  1212. .nf
  1213. .ft C
  1214. curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
  1215. .ft P
  1216. .fi
  1217. .UNINDENT
  1218. .UNINDENT
  1219. .sp
  1220. Response contains the same output as \fBGET /rest/db/need\fP
  1221. .SS POST /rest/db/revert
  1222. .sp
  1223. New in version 0.14.50.
  1224. .sp
  1225. Request revert of a receive only folder. Reverting a folder means to undo
  1226. all local changes. This API call does nothing if the folder is not a receive
  1227. only folder.
  1228. .sp
  1229. Takes the mandatory parameter \fIfolder\fP (folder ID).
  1230. .INDENT 0.0
  1231. .INDENT 3.5
  1232. .sp
  1233. .nf
  1234. .ft C
  1235. curl \-X POST \-H X\-API\-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
  1236. .ft P
  1237. .fi
  1238. .UNINDENT
  1239. .UNINDENT
  1240. .SS POST /rest/db/scan
  1241. .sp
  1242. Request immediate scan. Takes the optional parameters \fBfolder\fP (folder ID),
  1243. \fBsub\fP (path relative to the folder root) and \fBnext\fP (time in seconds). If
  1244. \fBfolder\fP is omitted or empty all folders are scanned. If \fBsub\fP is given,
  1245. only this path (and children, in case it’s a directory) is scanned. The \fBnext\fP
  1246. argument delays Syncthing’s automated rescan interval for a given amount of
  1247. seconds.
  1248. .sp
  1249. Requesting scan of a path that no longer exists, but previously did, is
  1250. valid and will result in Syncthing noticing the deletion of the path in
  1251. question.
  1252. .sp
  1253. Returns status 200 and no content upon success, or status 500 and a
  1254. plain text error if an error occurred during scanning.
  1255. .INDENT 0.0
  1256. .INDENT 3.5
  1257. .sp
  1258. .nf
  1259. .ft C
  1260. curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
  1261. .ft P
  1262. .fi
  1263. .UNINDENT
  1264. .UNINDENT
  1265. .SS GET /rest/db/status
  1266. .sp
  1267. Returns information about the current status of a folder.
  1268. .sp
  1269. Parameters: \fBfolder\fP, the ID of a folder.
  1270. .INDENT 0.0
  1271. .INDENT 3.5
  1272. .sp
  1273. .nf
  1274. .ft C
  1275. {
  1276. "globalBytes": 0,
  1277. "globalDeleted": 0,
  1278. "globalDirectories": 0,
  1279. "globalFiles": 0,
  1280. "globalSymlinks": 0,
  1281. "globalTotalItems": 0,
  1282. "ignorePatterns": false,
  1283. "inSyncBytes": 0,
  1284. "inSyncFiles": 0,
  1285. "invalid": "",
  1286. "localBytes": 0,
  1287. "localDeleted": 0,
  1288. "localDirectories": 0,
  1289. "localFiles": 0,
  1290. "localSymlinks": 0,
  1291. "localTotalItems": 0,
  1292. "needBytes": 0,
  1293. "needDeletes": 0,
  1294. "needDirectories": 0,
  1295. "needFiles": 0,
  1296. "needSymlinks": 0,
  1297. "needTotalItems": 0,
  1298. "pullErrors": 0,
  1299. "receiveOnlyChangedBytes": 0,
  1300. "receiveOnlyChangedDeletes": 0,
  1301. "receiveOnlyChangedDirectories": 0,
  1302. "receiveOnlyChangedFiles": 0,
  1303. "receiveOnlyChangedSymlinks": 0,
  1304. "receiveOnlyTotalItems": 0,
  1305. "sequence": 0,
  1306. "state": "idle",
  1307. "stateChanged": "2018\-08\-08T07:04:57.301064781+02:00",
  1308. "version": 0
  1309. }
  1310. .ft P
  1311. .fi
  1312. .UNINDENT
  1313. .UNINDENT
  1314. .sp
  1315. The various fields have the following meaning:
  1316. .INDENT 0.0
  1317. .TP
  1318. .B global*:
  1319. Data in the cluster latest version.
  1320. .TP
  1321. .B inSync*:
  1322. Data that is locally the same as the cluster latest version.
  1323. .TP
  1324. .B local*:
  1325. Data that is locally present, regardless of whether it’s the same or different version as the cluster latest version.
  1326. .TP
  1327. .B need*:
  1328. Data that is needed to become up to date with the cluster latest version (i.e., data that is out of sync).
  1329. .TP
  1330. .B receiveOnlyChanged*:
  1331. Data that has changed locally in a receive only folder, and thus not been sent to the cluster.
  1332. .TP
  1333. .B invalid:
  1334. Deprecated, always empty.
  1335. .TP
  1336. .B pullErrors:
  1337. The number of files that failed to sync during the last sync operations.
  1338. .TP
  1339. .B sequence:
  1340. The current folder sequence number.
  1341. .TP
  1342. .B state:
  1343. The current folder state.
  1344. .TP
  1345. .B stateChanged:
  1346. When the folder state last changed.
  1347. .TP
  1348. .B version:
  1349. Deprecated, equivalent to the sequence number.
  1350. .UNINDENT
  1351. .sp
  1352. \fBNOTE:\fP
  1353. .INDENT 0.0
  1354. .INDENT 3.5
  1355. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  1356. .UNINDENT
  1357. .UNINDENT
  1358. .SH EVENT ENDPOINTS
  1359. .SS GET /rest/events
  1360. .sp
  1361. To receive events, perform a HTTP GET of \fB/rest/events\fP\&.
  1362. .sp
  1363. To filter the event list, in effect creating a specific subscription for
  1364. only the desired event types, add a parameter
  1365. \fBevents=EventTypeA,EventTypeB,...\fP where the event types are any of the event\-types\&.
  1366. .sp
  1367. The optional parameter \fBsince=<lastSeenID>\fP sets the ID of the last event
  1368. you’ve already seen. Syncthing returns a JSON encoded array of event objects,
  1369. starting at the event just after the one with this last seen ID. The default
  1370. value is 0, which returns all events. There is a limit to the number of events
  1371. buffered, so if the rate of events is high or the time between polling calls is
  1372. long some events might be missed. This can be detected by noting a discontinuity
  1373. in the event IDs.
  1374. .sp
  1375. If no new events are produced since \fB<lastSeenID>\fP, the HTTP call blocks and
  1376. waits for new events to happen before returning. By default it times out after
  1377. 60 seconds returning an empty array. The time out duration can be customized
  1378. with the optional parameter \fBtimeout=<seconds>\fP\&.
  1379. .sp
  1380. To receive only a limited number of events, add the \fBlimit=<n>\fP parameter with a
  1381. suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This
  1382. can be used to catch up with the latest event ID after a disconnection for
  1383. example: \fB/rest/events?since=0&limit=1\fP\&.
  1384. .SH STATISTICS ENDPOINTS
  1385. .SS GET /rest/stats/device
  1386. .sp
  1387. Returns general statistics about devices. Currently, only contains the
  1388. time the device was last seen.
  1389. .INDENT 0.0
  1390. .INDENT 3.5
  1391. .sp
  1392. .nf
  1393. .ft C
  1394. $ curl \-s http://localhost:8384/rest/stats/device | json
  1395. {
  1396. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  1397. "lastSeen" : "2015\-04\-18T11:21:31.3256277+01:00"
  1398. }
  1399. }
  1400. .ft P
  1401. .fi
  1402. .UNINDENT
  1403. .UNINDENT
  1404. .SS GET /rest/stats/folder
  1405. .sp
  1406. Returns general statistics about folders. Currently contains the
  1407. last scan time and the last synced file.
  1408. .INDENT 0.0
  1409. .INDENT 3.5
  1410. .sp
  1411. .nf
  1412. .ft C
  1413. $ curl \-s http://localhost:8384/rest/stats/folder | json
  1414. {
  1415. "folderid" : {
  1416. "lastScan": "2016\-06\-02T13:28:01.288181412\-04:00",
  1417. "lastFile" : {
  1418. "filename" : "file/name",
  1419. "at" : "2015\-04\-16T22:04:18.3066971+01:00"
  1420. }
  1421. }
  1422. }
  1423. .ft P
  1424. .fi
  1425. .UNINDENT
  1426. .UNINDENT
  1427. .SH MISC SERVICES ENDPOINTS
  1428. .SS GET /rest/svc/deviceid
  1429. .sp
  1430. Verifies and formats a device ID. Accepts all currently valid formats
  1431. (52 or 56 characters with or without separators, upper or lower case,
  1432. with trivial substitutions). Takes one parameter, \fBid\fP, and returns
  1433. either a valid device ID in modern format, or an error.
  1434. .INDENT 0.0
  1435. .INDENT 3.5
  1436. .sp
  1437. .nf
  1438. .ft C
  1439. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json
  1440. {
  1441. "error": "device ID invalid: incorrect length"
  1442. }
  1443. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
  1444. {
  1445. "id": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2"
  1446. }
  1447. .ft P
  1448. .fi
  1449. .UNINDENT
  1450. .UNINDENT
  1451. .SS GET /rest/svc/lang
  1452. .sp
  1453. Returns a list of canonicalized localization codes, as picked up from
  1454. the \fBAccept\-Language\fP header sent by the browser.
  1455. .INDENT 0.0
  1456. .INDENT 3.5
  1457. .sp
  1458. .nf
  1459. .ft C
  1460. ["sv_sv","sv","en_us","en"]
  1461. .ft P
  1462. .fi
  1463. .UNINDENT
  1464. .UNINDENT
  1465. .SS GET /rest/svc/random/string
  1466. .sp
  1467. Returns a strong random generated string (alphanumeric) of the specified length. Takes the \fBlength\fP parameter.
  1468. .INDENT 0.0
  1469. .INDENT 3.5
  1470. .sp
  1471. .nf
  1472. .ft C
  1473. {
  1474. "random": "FdPaEaZQ56sXEKYNxpgF"
  1475. }
  1476. .ft P
  1477. .fi
  1478. .UNINDENT
  1479. .UNINDENT
  1480. .SS GET /rest/svc/report
  1481. .sp
  1482. Returns the data sent in the anonymous usage report.
  1483. .INDENT 0.0
  1484. .INDENT 3.5
  1485. .sp
  1486. .nf
  1487. .ft C
  1488. {
  1489. "folderMaxMiB" : 0,
  1490. "platform" : "linux\-amd64",
  1491. "totMiB" : 0,
  1492. "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",
  1493. "upgradeAllowedManual" : true,
  1494. "totFiles" : 3,
  1495. "folderUses" : {
  1496. "ignorePerms" : 0,
  1497. "autoNormalize" : 0,
  1498. "sendonly" : 0,
  1499. "ignoreDelete" : 0
  1500. },
  1501. "memoryUsageMiB" : 13,
  1502. "version" : "v0.12.2",
  1503. "sha256Perf" : 27.28,
  1504. "numFolders" : 2,
  1505. "memorySize" : 1992,
  1506. "announce" : {
  1507. "defaultServersIP" : 0,
  1508. "otherServers" : 0,
  1509. "globalEnabled" : false,
  1510. "defaultServersDNS" : 1,
  1511. "localEnabled" : false
  1512. },
  1513. "usesRateLimit" : false,
  1514. "numCPU" : 2,
  1515. "uniqueID" : "",
  1516. "urVersion" : 2,
  1517. "rescanIntvs" : [
  1518. 60,
  1519. 60
  1520. ],
  1521. "numDevices" : 2,
  1522. "folderMaxFiles" : 3,
  1523. "relays" : {
  1524. "defaultServers" : 1,
  1525. "enabled" : true,
  1526. "otherServers" : 0
  1527. },
  1528. "deviceUses" : {
  1529. "compressMetadata" : 1,
  1530. "customCertName" : 0,
  1531. "staticAddr" : 1,
  1532. "compressAlways" : 0,
  1533. "compressNever" : 1,
  1534. "introducer" : 0,
  1535. "dynamicAddr" : 1
  1536. },
  1537. "upgradeAllowedAuto" : false
  1538. }
  1539. .ft P
  1540. .fi
  1541. .UNINDENT
  1542. .UNINDENT
  1543. .SH AUTHOR
  1544. The Syncthing Authors
  1545. .SH COPYRIGHT
  1546. 2014-2019, The Syncthing Authors
  1547. .\" Generated by docutils manpage writer.
  1548. .