syncthing-rest-api.7 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852
  1. .\" Man page generated from reStructuredText.
  2. .
  3. .TH "SYNCTHING-REST-API" "7" "January 30, 2016" "v0.12" "Syncthing"
  4. .SH NAME
  5. syncthing-rest-api \- REST API
  6. .
  7. .nr rst2man-indent-level 0
  8. .
  9. .de1 rstReportMargin
  10. \\$1 \\n[an-margin]
  11. level \\n[rst2man-indent-level]
  12. level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13. -
  14. \\n[rst2man-indent0]
  15. \\n[rst2man-indent1]
  16. \\n[rst2man-indent2]
  17. ..
  18. .de1 INDENT
  19. .\" .rstReportMargin pre:
  20. . RS \\$1
  21. . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22. . nr rst2man-indent-level +1
  23. .\" .rstReportMargin post:
  24. ..
  25. .de UNINDENT
  26. . RE
  27. .\" indent \\n[an-margin]
  28. .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29. .nr rst2man-indent-level -1
  30. .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31. .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32. ..
  33. .SH DESCRIPTION
  34. .sp
  35. Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
  36. the GUI code (JavaScript) and can be used by other processes wishing to control
  37. Syncthing. In most cases both the input and output data is in JSON format. The
  38. interface is subject to change.
  39. .SH API KEY
  40. .sp
  41. To use the POST methods, or \fIany\fP method when authentication is enabled, an API
  42. key must be set and used. The API key can be generated in the GUI, or set in the
  43. \fBconfiguration/gui/apikey\fP element in the configuration file. To use an API
  44. key, set the request header \fBX\-API\-Key\fP to the API key value. For example,
  45. \fBcurl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be
  46. used to invoke authenticated POST methods via \fBcurl\fP\&.
  47. .SH SYSTEM ENDPOINTS
  48. .SS GET /rest/system/config
  49. .sp
  50. Returns the current configuration.
  51. .INDENT 0.0
  52. .INDENT 3.5
  53. .sp
  54. .nf
  55. .ft C
  56. {
  57. # etc
  58. }
  59. .ft P
  60. .fi
  61. .UNINDENT
  62. .UNINDENT
  63. .SS GET /rest/system/config/insync
  64. .sp
  65. Returns whether the config is in sync, i.e. whether the running
  66. configuration is the same as that on disk.
  67. .INDENT 0.0
  68. .INDENT 3.5
  69. .sp
  70. .nf
  71. .ft C
  72. {
  73. "configInSync": true
  74. }
  75. .ft P
  76. .fi
  77. .UNINDENT
  78. .UNINDENT
  79. .SS POST /rest/system/config
  80. .sp
  81. Post the full contents of the configuration, in the same format as returned by
  82. the corresponding GET request. The configuration will be saved to disk and the
  83. \fBconfigInSync\fP flag set to false. Restart Syncthing to activate.
  84. .SS GET /rest/system/connections
  85. .sp
  86. \fBNOTE:\fP
  87. .INDENT 0.0
  88. .INDENT 3.5
  89. Return format changed in 0.12.0.
  90. .UNINDENT
  91. .UNINDENT
  92. .sp
  93. Returns the list of configured devices and some metadata associated
  94. with them. The list also contains the local device itself as not connected.
  95. .INDENT 0.0
  96. .INDENT 3.5
  97. .sp
  98. .nf
  99. .ft C
  100. {
  101. "total" : {
  102. "paused" : false,
  103. "clientVersion" : "",
  104. "at" : "2015\-11\-07T17:29:47.691637262+01:00",
  105. "connected" : false,
  106. "inBytesTotal" : 1479,
  107. "type" : "direct\-accept",
  108. "outBytesTotal" : 1318,
  109. "address" : ""
  110. },
  111. "connections" : {
  112. "YZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC" : {
  113. "connected" : true,
  114. "inBytesTotal" : 556,
  115. "paused" : false,
  116. "at" : "2015\-11\-07T17:29:47.691548971+01:00",
  117. "clientVersion" : "v0.12.1",
  118. "address" : "127.0.0.1:22002",
  119. "type" : "direct\-dial",
  120. "outBytesTotal" : 550
  121. },
  122. "DOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA" : {
  123. "outBytesTotal" : 0,
  124. "type" : "direct\-accept",
  125. "address" : "",
  126. "at" : "0001\-01\-01T00:00:00Z",
  127. "clientVersion" : "",
  128. "paused" : false,
  129. "inBytesTotal" : 0,
  130. "connected" : false
  131. },
  132. "UYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4" : {
  133. "address" : "",
  134. "type" : "direct\-accept",
  135. "outBytesTotal" : 0,
  136. "connected" : false,
  137. "inBytesTotal" : 0,
  138. "paused" : false,
  139. "at" : "0001\-01\-01T00:00:00Z",
  140. "clientVersion" : ""
  141. }
  142. }
  143. }
  144. .ft P
  145. .fi
  146. .UNINDENT
  147. .UNINDENT
  148. .SS GET /rest/system/debug
  149. .sp
  150. New in version 0.12.0.
  151. .sp
  152. Returns the set of debug facilities and which of them are currently enabled.
  153. .INDENT 0.0
  154. .INDENT 3.5
  155. .sp
  156. .nf
  157. .ft C
  158. {
  159. "enabled": [
  160. "beacon"
  161. ],
  162. "facilities": {
  163. "beacon": "Multicast and broadcast discovery",
  164. "config": "Configuration loading and saving",
  165. "connections": "Connection handling",
  166. "db": "The database layer",
  167. "dialer": "Dialing connections",
  168. "discover": "Remote device discovery",
  169. "events": "Event generation and logging",
  170. "http": "REST API",
  171. "main": "Main package",
  172. "model": "The root hub",
  173. "protocol": "The BEP protocol",
  174. "relay": "Relay connection handling",
  175. "scanner": "File change detection and hashing",
  176. "stats": "Persistent device and folder statistics",
  177. "sync": "Mutexes",
  178. "upgrade": "Binary upgrades",
  179. "upnp": "UPnP discovery and port mapping",
  180. "versioner": "File versioning"
  181. }
  182. }
  183. .ft P
  184. .fi
  185. .UNINDENT
  186. .UNINDENT
  187. .SS POST /rest/system/debug
  188. .sp
  189. New in version 0.12.0.
  190. .sp
  191. Enables or disables debugging for specified facilities. Give one or both of
  192. \fBenable\fP and \fBdisable\fP query parameters, with comma separated facility
  193. names. To disable debugging of the beacon and discovery packages, and enable it
  194. for config and db:
  195. .INDENT 0.0
  196. .INDENT 3.5
  197. .sp
  198. .nf
  199. .ft C
  200. $ curl \-H X\-API\-Key:abc123 \-X POST \(aqhttp://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db\(aq
  201. .ft P
  202. .fi
  203. .UNINDENT
  204. .UNINDENT
  205. .SS GET /rest/system/discovery
  206. .sp
  207. Returns the contents of the local discovery cache.
  208. .INDENT 0.0
  209. .INDENT 3.5
  210. .sp
  211. .nf
  212. .ft C
  213. {
  214. "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [
  215. "192.162.129.11:22000"
  216. ]
  217. }
  218. .ft P
  219. .fi
  220. .UNINDENT
  221. .UNINDENT
  222. .SS POST /rest/system/discovery
  223. .sp
  224. \fBNOTE:\fP
  225. .INDENT 0.0
  226. .INDENT 3.5
  227. Removed in v0.12.0.
  228. .UNINDENT
  229. .UNINDENT
  230. .sp
  231. Post with the query parameters \fBdevice\fP and \fBaddr\fP to add entries to
  232. the discovery cache.
  233. .INDENT 0.0
  234. .INDENT 3.5
  235. .sp
  236. .nf
  237. .ft C
  238. curl \-X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
  239. # Or with the X\-API\-Key header:
  240. 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
  241. .ft P
  242. .fi
  243. .UNINDENT
  244. .UNINDENT
  245. .SS POST /rest/system/error/clear
  246. .sp
  247. Post with empty to body to remove all recent errors.
  248. .SS GET /rest/system/error
  249. .sp
  250. \fBNOTE:\fP
  251. .INDENT 0.0
  252. .INDENT 3.5
  253. Return format changed in 0.12.0.
  254. .UNINDENT
  255. .UNINDENT
  256. .sp
  257. Returns the list of recent errors.
  258. .INDENT 0.0
  259. .INDENT 3.5
  260. .sp
  261. .nf
  262. .ft C
  263. {
  264. "errors": [
  265. {
  266. "when": "2014\-09\-18T12:59:26.549953186+02:00",
  267. "message": "This is an error string"
  268. }
  269. ]
  270. }
  271. .ft P
  272. .fi
  273. .UNINDENT
  274. .UNINDENT
  275. .SS POST /rest/system/error
  276. .sp
  277. Post with an error message in the body (plain text) to register a new
  278. error. The new error will be displayed on any active GUI clients.
  279. .SS GET /rest/system/log
  280. .sp
  281. New in version 0.12.0.
  282. .sp
  283. Returns the list of recent log entries.
  284. .INDENT 0.0
  285. .INDENT 3.5
  286. .sp
  287. .nf
  288. .ft C
  289. {
  290. "messages": [
  291. {
  292. "when": "2014\-09\-18T12:59:26.549953186+02:00",
  293. "message": "This is a log entry"
  294. }
  295. ]
  296. }
  297. .ft P
  298. .fi
  299. .UNINDENT
  300. .UNINDENT
  301. .SS GET /rest/system/ping
  302. .sp
  303. Returns a \fB{"ping": "pong"}\fP object.
  304. .INDENT 0.0
  305. .INDENT 3.5
  306. .sp
  307. .nf
  308. .ft C
  309. {
  310. "ping": "pong"
  311. }
  312. .ft P
  313. .fi
  314. .UNINDENT
  315. .UNINDENT
  316. .SS POST /rest/system/ping
  317. .sp
  318. Returns a \fB{"ping": "pong"}\fP object.
  319. .sp
  320. \fBNOTE:\fP
  321. .INDENT 0.0
  322. .INDENT 3.5
  323. Due to being a POST request, this method requires using an API key or CSRF token, as opposed to the GET request to the same URL.
  324. .UNINDENT
  325. .UNINDENT
  326. .SS POST /rest/system/reset
  327. .sp
  328. Post with empty body to erase the current index database and restart
  329. Syncthing. With no query parameters, the entire database is erased from disk.
  330. By specifying the \fBfolder\fP parameter with a valid folder ID, only
  331. information for that folder will be erased:
  332. .INDENT 0.0
  333. .INDENT 3.5
  334. .sp
  335. .nf
  336. .ft C
  337. $ curl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/system/reset?folder=default
  338. .ft P
  339. .fi
  340. .UNINDENT
  341. .UNINDENT
  342. .SS POST /rest/system/restart
  343. .sp
  344. Post with empty body to immediately restart Syncthing.
  345. .SS POST /rest/system/shutdown
  346. .sp
  347. Post with empty body to cause Syncthing to exit and not restart.
  348. .SS GET /rest/system/status
  349. .sp
  350. Returns information about current system status and resource usage.
  351. .INDENT 0.0
  352. .INDENT 3.5
  353. .sp
  354. .nf
  355. .ft C
  356. {
  357. "alloc": 30618136,
  358. "cpuPercent": 0.006944836512046966,
  359. "extAnnounceOK": {
  360. "udp4://announce.syncthing.net:22026": true,
  361. "udp6://announce\-v6.syncthing.net:22026": true
  362. },
  363. "goroutines": 49,
  364. "myID": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2",
  365. "pathSeparator": "/",
  366. "sys": 42092792,
  367. "tilde": "/Users/jb"
  368. }
  369. .ft P
  370. .fi
  371. .UNINDENT
  372. .UNINDENT
  373. .SS GET /rest/system/upgrade
  374. .sp
  375. Checks for a possible upgrade and returns an object describing the
  376. newest version and upgrade possibility.
  377. .INDENT 0.0
  378. .INDENT 3.5
  379. .sp
  380. .nf
  381. .ft C
  382. {
  383. "latest": "v0.10.27",
  384. "newer": false,
  385. "running": "v0.10.27+5\-g36c93b7"
  386. }
  387. .ft P
  388. .fi
  389. .UNINDENT
  390. .UNINDENT
  391. .SS POST /rest/system/upgrade
  392. .sp
  393. Perform an upgrade to the newest released version and restart. Does
  394. nothing if there is no newer version than currently running.
  395. .SS GET /rest/system/version
  396. .sp
  397. Returns the current Syncthing version information.
  398. .INDENT 0.0
  399. .INDENT 3.5
  400. .sp
  401. .nf
  402. .ft C
  403. {
  404. "arch": "amd64",
  405. "longVersion": "syncthing v0.10.27+3\-gea8c3de (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 11:01:29 UTC",
  406. "os": "darwin",
  407. "version": "v0.10.27+3\-gea8c3de"
  408. }
  409. .ft P
  410. .fi
  411. .UNINDENT
  412. .UNINDENT
  413. .SH DATABASE ENDPOINTS
  414. .SS GET /rest/db/browse
  415. .sp
  416. Returns the directory tree of the global model. Directories are always
  417. JSON objects (map/dictionary), and files are always arrays of
  418. modification time and size. The first integer is the files modification
  419. time, and the second integer is the file size.
  420. .sp
  421. The call takes one mandatory \fBfolder\fP parameter and two optional
  422. parameters. Optional parameter \fBlevels\fP defines how deep within the
  423. tree we want to dwell down (0 based, defaults to unlimited depth)
  424. Optional parameter \fBprefix\fP defines a prefix within the tree where to
  425. start building the structure.
  426. .INDENT 0.0
  427. .INDENT 3.5
  428. .sp
  429. .nf
  430. .ft C
  431. $ curl \-s http://localhost:8384/rest/db/browse?folder=default | json_pp
  432. {
  433. "directory": {
  434. "file": ["2015\-04\-20T22:20:45+09:00", 130940928],
  435. "subdirectory": {
  436. "another file": ["2015\-04\-20T22:20:45+09:00", 130940928]
  437. }
  438. },
  439. "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
  440. }
  441. $ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=0 | json_pp
  442. {
  443. "directory": {},
  444. "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
  445. }
  446. $ curl \-s http://localhost:8384/rest/db/browse?folder=default&levels=1 | json_pp
  447. {
  448. "directory": {
  449. "file": ["2015\-04\-20T22:20:45+09:00", 130940928],
  450. "subdirectory": {}
  451. },
  452. "rootfile": ["2015\-04\-20T22:20:45+09:00", 130940928]
  453. }
  454. $ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory/subdirectory | json_pp
  455. {
  456. "another file": ["2015\-04\-20T22:20:45+09:00", 130940928]
  457. }
  458. $ curl \-s http://localhost:8384/rest/db/browse?folder=default&prefix=directory&levels=0 | json_pp
  459. {
  460. "file": ["2015\-04\-20T22:20:45+09:00", 130940928],
  461. "subdirectory": {}
  462. }
  463. .ft P
  464. .fi
  465. .UNINDENT
  466. .UNINDENT
  467. .sp
  468. \fBNOTE:\fP
  469. .INDENT 0.0
  470. .INDENT 3.5
  471. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  472. .UNINDENT
  473. .UNINDENT
  474. .SS GET /rest/db/completion
  475. .sp
  476. Returns the completion percentage (0 to 100) for a given device and
  477. folder. Takes \fBdevice\fP and \fBfolder\fP parameters.
  478. .INDENT 0.0
  479. .INDENT 3.5
  480. .sp
  481. .nf
  482. .ft C
  483. {
  484. "completion": 0
  485. }
  486. .ft P
  487. .fi
  488. .UNINDENT
  489. .UNINDENT
  490. .sp
  491. \fBNOTE:\fP
  492. .INDENT 0.0
  493. .INDENT 3.5
  494. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  495. .UNINDENT
  496. .UNINDENT
  497. .SS GET /rest/db/file
  498. .sp
  499. Returns most data available about a given file, including version and
  500. availability. Takes \fBfolder\fP and \fBfile\fP parameters.
  501. .INDENT 0.0
  502. .INDENT 3.5
  503. .sp
  504. .nf
  505. .ft C
  506. {
  507. "availability": [
  508. "I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU"
  509. ],
  510. "global": {
  511. "flags": "0644",
  512. "localVersion": 3,
  513. "modified": "2015\-04\-20T22:20:45+09:00",
  514. "name": "util.go",
  515. "numBlocks": 1,
  516. "size": 9642,
  517. "version": [
  518. "5407294127585413568:1"
  519. ]
  520. },
  521. "local": {
  522. "flags": "0644",
  523. "localVersion": 4,
  524. "modified": "2015\-04\-20T22:20:45+09:00",
  525. "name": "util.go",
  526. "numBlocks": 1,
  527. "size": 9642,
  528. "version": [
  529. "5407294127585413568:1"
  530. ]
  531. }
  532. }
  533. .ft P
  534. .fi
  535. .UNINDENT
  536. .UNINDENT
  537. .SS GET /rest/db/ignores
  538. .sp
  539. Takes one parameter, \fBfolder\fP, and returns the content of the
  540. \fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBpatterns\fP,
  541. provides a compiled version of all included ignore patterns in the form
  542. of regular expressions. Excluded items in the \fBpatterns\fP field have a
  543. nonstandard \fB(?exclude)\fP marker in front of the regular expression.
  544. .INDENT 0.0
  545. .INDENT 3.5
  546. .sp
  547. .nf
  548. .ft C
  549. {
  550. "ignore": [
  551. "/Backups"
  552. ],
  553. "patterns": [
  554. "(?i)^Backups$",
  555. "(?i)^Backups/.*$"
  556. ]
  557. }
  558. .ft P
  559. .fi
  560. .UNINDENT
  561. .UNINDENT
  562. .SS POST /rest/db/ignores
  563. .sp
  564. Expects a format similar to the output of \fBGET\fP call, but only
  565. containing the \fBignore\fP field (\fBpatterns\fP field should be omitted).
  566. It takes one parameter, \fBfolder\fP, and either updates the content of
  567. the \fB\&.stignore\fP echoing it back as a response, or returns an error.
  568. .SS GET /rest/db/need
  569. .sp
  570. Takes one parameter, \fBfolder\fP, and returns lists of files which are
  571. needed by this device in order for it to become in sync.
  572. .INDENT 0.0
  573. .INDENT 3.5
  574. .sp
  575. .nf
  576. .ft C
  577. {
  578. # Files currently being downloaded
  579. "progress": [
  580. {
  581. "flags": "0755",
  582. "localVersion": 6,
  583. "modified": "2015\-04\-20T23:06:12+09:00",
  584. "name": "ls",
  585. "size": 34640,
  586. "version": [
  587. "5157751870738175669:1"
  588. ]
  589. }
  590. ],
  591. # Files queued to be downloaded next (as per array order)
  592. "queued": [
  593. ...
  594. ],
  595. # Files to be downloaded after all queued files will be downloaded.
  596. # This happens when we start downloading files, and new files get added while we are downloading.
  597. "rest": [
  598. ...
  599. ]
  600. }
  601. .ft P
  602. .fi
  603. .UNINDENT
  604. .UNINDENT
  605. .sp
  606. \fBNOTE:\fP
  607. .INDENT 0.0
  608. .INDENT 3.5
  609. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  610. .UNINDENT
  611. .UNINDENT
  612. .SS POST /rest/db/prio
  613. .sp
  614. Moves the file to the top of the download queue.
  615. .INDENT 0.0
  616. .INDENT 3.5
  617. .sp
  618. .nf
  619. .ft C
  620. curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
  621. .ft P
  622. .fi
  623. .UNINDENT
  624. .UNINDENT
  625. .sp
  626. Response contains the same output as \fBGET /rest/db/need\fP
  627. .SS POST /rest/db/scan
  628. .sp
  629. Request immediate rescan of a folder, or a specific path within a folder.
  630. Takes the mandatory parameter \fIfolder\fP (folder ID), an optional parameter
  631. \fBsub\fP (path relative to the folder root) and an optional parameter \fBnext\fP\&. If
  632. \fBsub\fP is omitted or empty, the entire folder is scanned for changes, otherwise
  633. only the given path (and children, in case it\(aqs a directory) is scanned. The
  634. \fBnext\fP argument delays Syncthing\(aqs automated rescan interval for a given
  635. amount of seconds.
  636. .sp
  637. Requesting scan of a path that no longer exists, but previously did, is
  638. valid and will result in Syncthing noticing the deletion of the path in
  639. question.
  640. .sp
  641. Returns status 200 and no content upon success, or status 500 and a
  642. plain text error if an error occurred during scanning.
  643. .INDENT 0.0
  644. .INDENT 3.5
  645. .sp
  646. .nf
  647. .ft C
  648. curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
  649. .ft P
  650. .fi
  651. .UNINDENT
  652. .UNINDENT
  653. .SS GET /rest/db/status
  654. .sp
  655. Returns information about the current status of a folder.
  656. .sp
  657. Parameters: \fBfolder\fP, the ID of a folder.
  658. .INDENT 0.0
  659. .INDENT 3.5
  660. .sp
  661. .nf
  662. .ft C
  663. {
  664. # latest version according to cluster:
  665. "globalBytes": 13173473780,
  666. "globalDeleted": 1847,
  667. "globalFiles": 42106,
  668. # what we have locally:
  669. "localBytes": 13173473780,
  670. "localDeleted": 1847,
  671. "localFiles": 42106,
  672. # which part of what we have locally is the latest cluster version:
  673. "inSyncBytes": 13173473780,
  674. "inSyncFiles": 42106,
  675. # which part of what we have locally should be fetched from the cluster:
  676. "needBytes": 0,
  677. "needFiles": 0,
  678. # various other metadata
  679. "ignorePatterns": true,
  680. "invalid": "",
  681. "state": "idle",
  682. "stateChanged": "2015\-03\-16T21:47:28.750853241+01:00",
  683. "version": 71989
  684. }
  685. .ft P
  686. .fi
  687. .UNINDENT
  688. .UNINDENT
  689. .sp
  690. \fBNOTE:\fP
  691. .INDENT 0.0
  692. .INDENT 3.5
  693. This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
  694. .UNINDENT
  695. .UNINDENT
  696. .SH STATISTICS ENDPOINTS
  697. .SS GET /rest/stats/device
  698. .sp
  699. Returns general statistics about devices. Currently, only contains the
  700. time the device was last seen.
  701. .INDENT 0.0
  702. .INDENT 3.5
  703. .sp
  704. .nf
  705. .ft C
  706. $ curl \-s http://localhost:8384/rest/stats/device | json
  707. {
  708. "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2": {
  709. "lastSeen" : "2015\-04\-18T11:21:31.3256277+01:00"
  710. }
  711. }
  712. .ft P
  713. .fi
  714. .UNINDENT
  715. .UNINDENT
  716. .SS GET /rest/stats/folder
  717. .sp
  718. Returns general statistics about folders. Currently, only contains the
  719. last synced file.
  720. .INDENT 0.0
  721. .INDENT 3.5
  722. .sp
  723. .nf
  724. .ft C
  725. $ curl \-s http://localhost:8384/rest/stats/folder | json
  726. {
  727. "folderid" : {
  728. "lastFile" : {
  729. "filename" : "file/name",
  730. "at" : "2015\-04\-16T22:04:18.3066971+01:00"
  731. }
  732. }
  733. }
  734. .ft P
  735. .fi
  736. .UNINDENT
  737. .UNINDENT
  738. .SH MISC SERVICES ENDPOINTS
  739. .SS GET /rest/svc/deviceid
  740. .sp
  741. Verifies and formats a device ID. Accepts all currently valid formats
  742. (52 or 56 characters with or without separators, upper or lower case,
  743. with trivial substitutions). Takes one parameter, \fBid\fP, and returns
  744. either a valid device ID in modern format, or an error.
  745. .INDENT 0.0
  746. .INDENT 3.5
  747. .sp
  748. .nf
  749. .ft C
  750. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json
  751. {
  752. "error": "device ID invalid: incorrect length"
  753. }
  754. $ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
  755. {
  756. "id": "P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2"
  757. }
  758. .ft P
  759. .fi
  760. .UNINDENT
  761. .UNINDENT
  762. .SS GET /rest/svc/lang
  763. .sp
  764. Returns a list of canonicalized localization codes, as picked up from
  765. the \fBAccept\-Language\fP header sent by the browser.
  766. .INDENT 0.0
  767. .INDENT 3.5
  768. .sp
  769. .nf
  770. .ft C
  771. ["sv_sv","sv","en_us","en"]
  772. .ft P
  773. .fi
  774. .UNINDENT
  775. .UNINDENT
  776. .SS GET /rest/svc/report
  777. .sp
  778. Returns the data sent in the anonymous usage report.
  779. .INDENT 0.0
  780. .INDENT 3.5
  781. .sp
  782. .nf
  783. .ft C
  784. {
  785. "folderMaxMiB" : 0,
  786. "platform" : "linux\-amd64",
  787. "totMiB" : 0,
  788. "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",
  789. "upgradeAllowedManual" : true,
  790. "totFiles" : 3,
  791. "folderUses" : {
  792. "ignorePerms" : 0,
  793. "autoNormalize" : 0,
  794. "readonly" : 0,
  795. "ignoreDelete" : 0
  796. },
  797. "memoryUsageMiB" : 13,
  798. "version" : "v0.12.2",
  799. "sha256Perf" : 27.28,
  800. "numFolders" : 2,
  801. "memorySize" : 1992,
  802. "announce" : {
  803. "defaultServersIP" : 0,
  804. "otherServers" : 0,
  805. "globalEnabled" : false,
  806. "defaultServersDNS" : 1,
  807. "localEnabled" : false
  808. },
  809. "usesRateLimit" : false,
  810. "numCPU" : 2,
  811. "uniqueID" : "",
  812. "urVersion" : 2,
  813. "rescanIntvs" : [
  814. 60,
  815. 60
  816. ],
  817. "numDevices" : 2,
  818. "folderMaxFiles" : 3,
  819. "relays" : {
  820. "defaultServers" : 1,
  821. "enabled" : true,
  822. "otherServers" : 0
  823. },
  824. "deviceUses" : {
  825. "compressMetadata" : 1,
  826. "customCertName" : 0,
  827. "staticAddr" : 1,
  828. "compressAlways" : 0,
  829. "compressNever" : 1,
  830. "introducer" : 0,
  831. "dynamicAddr" : 1
  832. },
  833. "upgradeAllowedAuto" : false
  834. }
  835. .ft P
  836. .fi
  837. .UNINDENT
  838. .UNINDENT
  839. .SH AUTHOR
  840. The Syncthing Authors
  841. .SH COPYRIGHT
  842. 2015, The Syncthing Authors
  843. .\" Generated by docutils manpage writer.
  844. .