1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972 |
- .\" Man page generated from reStructuredText.
- .
- .
- .nr rst2man-indent-level 0
- .
- .de1 rstReportMargin
- \\$1 \\n[an-margin]
- level \\n[rst2man-indent-level]
- level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
- -
- \\n[rst2man-indent0]
- \\n[rst2man-indent1]
- \\n[rst2man-indent2]
- ..
- .de1 INDENT
- .\" .rstReportMargin pre:
- . RS \\$1
- . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
- . nr rst2man-indent-level +1
- .\" .rstReportMargin post:
- ..
- .de UNINDENT
- . RE
- .\" indent \\n[an-margin]
- .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .nr rst2man-indent-level -1
- .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
- .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
- ..
- .TH "SYNCTHING-REST-API" "7" "Sep 04, 2024" "v1.27.11" "Syncthing"
- .SH NAME
- syncthing-rest-api \- REST API
- .sp
- Syncthing exposes a REST interface over HTTP on the GUI port. This is used by
- the GUI (from Javascript) and can be used by other processes wishing to control
- Syncthing. In most cases both the input and output data is in JSON format. The
- interface is subject to change.
- .SH API KEY
- .sp
- To use the REST API an API key must be set and used. The API key can be
- generated in the GUI, or set in the \fBconfiguration/gui/apikey\fP element in
- the configuration file. To use an API key, set the request header
- \fBX\-API\-Key\fP to the API key value, or set it as a \fBBearer\fP token in the
- \fBAuthorization\fP header. For example, \fBcurl \-X POST \-H \(dqX\-API\-Key: abc123\(dq
- http://localhost:8384/rest/...\fP or \fBcurl \-X POST \-H \(dqAuthorization: Bearer
- abc123\(dq http://localhost:8384/rest/...\fP can be used to invoke with \fBcurl\fP
- (add \fB\-k\fP flag when using HTTPS with a Syncthing generated or self signed
- certificate).
- .sp
- One exception to this requirement is \fB/rest/noauth\fP, you do not need an API
- key to use those endpoints. This way third\-party devices and services can do
- simple calls that don’t expose sensitive information without having to expose
- your API key.
- .SH RESULT PAGINATION
- .sp
- Some \fIGET\fP endpoints take optional \fBpage\fP and \fBperpage\fP arguments for
- pagination. No more than \fBperpage\fP (defaults to 65536 if not given) result
- entries are returned in an array. To access further entries, passing the
- \fBpage\fP parameter will advance in the results by that many pages. The actually
- used parameters are always returned as attributes in the response object.
- .SH SYSTEM ENDPOINTS
- .SS GET /rest/system/browse
- .sp
- Returns a list of directories matching the path given by the optional parameter
- \fBcurrent\fP\&. The path can use \X'tty: link https://pkg.go.dev/path/filepath#Match'\fI\%patterns as described in Go’s filepath package\fP <\fBhttps://pkg.go.dev/path/filepath#Match\fP>\X'tty: link'\&. A ‘*’ will always be appended
- to the given path (e.g. \fB/tmp/\fP matches all its subdirectories). If the option
- \fBcurrent\fP is not given, filesystem root paths are returned.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-H \(dqX\-API\-Key: yourkey\(dq localhost:8384/rest/system/browse | json_pp
- [
- \(dq/\(dq
- ]
- $ curl \-H \(dqX\-API\-Key: yourkey\(dq localhost:8384/rest/system/browse?current=/var/ | json_pp
- [
- \(dq/var/backups/\(dq,
- \(dq/var/cache/\(dq,
- \(dq/var/lib/\(dq,
- \(dq/var/local/\(dq,
- \(dq/var/lock/\(dq,
- \(dq/var/log/\(dq,
- \(dq/var/mail/\(dq,
- \(dq/var/opt/\(dq,
- \(dq/var/run/\(dq,
- \(dq/var/spool/\(dq,
- \(dq/var/tmp/\(dq
- ]
- $ curl \-H \(dqX\-API\-Key: yourkey\(dq localhost:8384/rest/system/browse?current=/var/*o | json_pp
- [
- \(dq/var/local/\(dq,
- \(dq/var/lock/\(dq,
- \(dq/var/log/\(dq,
- \(dq/var/opt/\(dq,
- \(dq/var/spool/\(dq
- ]
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/system/config (DEPRECATED)
- .sp
- Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use \fI\%/rest/config\fP
- instead.
- .sp
- Returns the current configuration.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqversion\(dq: 35,
- \(dqfolders\(dq: [
- {
- \(dqid\(dq: \(dqdefault\(dq,
- \(dqlabel\(dq: \(dqDefault Folder\(dq,
- \(dqfilesystemType\(dq: \(dqbasic\(dq,
- \(dqpath\(dq: \(dq...\(dq,
- \(dqtype\(dq: \(dqsendreceive\(dq,
- \(dqdevices\(dq: [
- {
- \(dqdeviceID\(dq: \(dq...\(dq,
- \(dqintroducedBy\(dq: \(dq\(dq,
- \(dqencryptionPassword\(dq: \(dq\(dq
- }
- ],
- \(dqrescanIntervalS\(dq: 3600,
- \(dqfsWatcherEnabled\(dq: true,
- \(dqfsWatcherDelayS\(dq: 10,
- \(dqignorePerms\(dq: false,
- \(dqautoNormalize\(dq: true,
- \(dqminDiskFree\(dq: {
- \(dqvalue\(dq: 1,
- \(dqunit\(dq: \(dq%\(dq
- },
- \(dqversioning\(dq: {
- \(dqtype\(dq: \(dq\(dq,
- \(dqparams\(dq: {},
- \(dqcleanupIntervalS\(dq: 3600,
- \(dqfsPath\(dq: \(dq\(dq,
- \(dqfsType\(dq: \(dqbasic\(dq
- },
- \(dqcopiers\(dq: 0,
- \(dqpullerMaxPendingKiB\(dq: 0,
- \(dqhashers\(dq: 0,
- \(dqorder\(dq: \(dqrandom\(dq,
- \(dqignoreDelete\(dq: false,
- \(dqscanProgressIntervalS\(dq: 0,
- \(dqpullerPauseS\(dq: 0,
- \(dqmaxConflicts\(dq: \-1,
- \(dqdisableSparseFiles\(dq: false,
- \(dqdisableTempIndexes\(dq: false,
- \(dqpaused\(dq: false,
- \(dqweakHashThresholdPct\(dq: 25,
- \(dqmarkerName\(dq: \(dq.stfolder\(dq,
- \(dqcopyOwnershipFromParent\(dq: false,
- \(dqmodTimeWindowS\(dq: 0,
- \(dqmaxConcurrentWrites\(dq: 2,
- \(dqdisableFsync\(dq: false,
- \(dqblockPullOrder\(dq: \(dqstandard\(dq,
- \(dqcopyRangeMethod\(dq: \(dqstandard\(dq,
- \(dqcaseSensitiveFS\(dq: false,
- \(dqjunctionsAsDirs\(dq: true
- }
- ],
- \(dqdevices\(dq: [
- {
- \(dqdeviceID\(dq: \(dq...\(dq,
- \(dqname\(dq: \(dqLaptop\(dq,
- \(dqaddresses\(dq: [
- \(dqdynamic\(dq,
- \(dqtcp://192.168.1.2:22000\(dq
- ],
- \(dqcompression\(dq: \(dqmetadata\(dq,
- \(dqcertName\(dq: \(dq\(dq,
- \(dqintroducer\(dq: false,
- \(dqskipIntroductionRemovals\(dq: false,
- \(dqintroducedBy\(dq: \(dq\(dq,
- \(dqpaused\(dq: false,
- \(dqallowedNetworks\(dq: [],
- \(dqautoAcceptFolders\(dq: false,
- \(dqmaxSendKbps\(dq: 0,
- \(dqmaxRecvKbps\(dq: 0,
- \(dqignoredFolders\(dq: [
- {
- \(dqtime\(dq: \(dq2022\-01\-09T19:09:52Z\(dq,
- \(dqid\(dq: \(dqbr63e\-wyhb7\(dq,
- \(dqlabel\(dq: \(dqFoo\(dq
- }
- ],
- \(dqmaxRequestKiB\(dq: 0,
- \(dquntrusted\(dq: false,
- \(dqremoteGUIPort\(dq: 0
- }
- ],
- \(dqgui\(dq: {
- \(dqenabled\(dq: true,
- \(dqaddress\(dq: \(dq127.0.0.1:8384\(dq,
- \(dqunixSocketPermissions\(dq: \(dq\(dq,
- \(dquser\(dq: \(dqUsername\(dq,
- \(dqpassword\(dq: \(dq$2a$10$ZFws69T4FlvWwsqeIwL.TOo5zOYqsa/.TxlUnsGYS.j3JvjFTmxo6\(dq,
- \(dqauthMode\(dq: \(dqstatic\(dq,
- \(dquseTLS\(dq: false,
- \(dqapiKey\(dq: \(dqk1dnz1Dd0rzTBjjFFh7CXPnrF12C49B1\(dq,
- \(dqinsecureAdminAccess\(dq: false,
- \(dqtheme\(dq: \(dqdefault\(dq,
- \(dqdebugging\(dq: false,
- \(dqinsecureSkipHostcheck\(dq: false,
- \(dqinsecureAllowFrameLoading\(dq: false
- },
- \(dqldap\(dq: {
- \(dqaddress\(dq: \(dq\(dq,
- \(dqbindDN\(dq: \(dq\(dq,
- \(dqtransport\(dq: \(dqplain\(dq,
- \(dqinsecureSkipVerify\(dq: false,
- \(dqsearchBaseDN\(dq: \(dq\(dq,
- \(dqsearchFilter\(dq: \(dq\(dq
- },
- \(dqoptions\(dq: {
- \(dqlistenAddresses\(dq: [
- \(dqdefault\(dq
- ],
- \(dqglobalAnnounceServers\(dq: [
- \(dqdefault\(dq
- ],
- \(dqglobalAnnounceEnabled\(dq: true,
- \(dqlocalAnnounceEnabled\(dq: true,
- \(dqlocalAnnouncePort\(dq: 21027,
- \(dqlocalAnnounceMCAddr\(dq: \(dq[ff12::8384]:21027\(dq,
- \(dqmaxSendKbps\(dq: 0,
- \(dqmaxRecvKbps\(dq: 0,
- \(dqreconnectionIntervalS\(dq: 60,
- \(dqrelaysEnabled\(dq: true,
- \(dqrelayReconnectIntervalM\(dq: 10,
- \(dqstartBrowser\(dq: true,
- \(dqnatEnabled\(dq: true,
- \(dqnatLeaseMinutes\(dq: 60,
- \(dqnatRenewalMinutes\(dq: 30,
- \(dqnatTimeoutSeconds\(dq: 10,
- \(dqurAccepted\(dq: 0,
- \(dqurSeen\(dq: 0,
- \(dqurUniqueId\(dq: \(dq...\(dq,
- \(dqurURL\(dq: \(dqhttps://data.syncthing.net/newdata\(dq,
- \(dqurPostInsecurely\(dq: false,
- \(dqurInitialDelayS\(dq: 1800,
- \(dqautoUpgradeIntervalH\(dq: 12,
- \(dqupgradeToPreReleases\(dq: false,
- \(dqkeepTemporariesH\(dq: 24,
- \(dqcacheIgnoredFiles\(dq: false,
- \(dqprogressUpdateIntervalS\(dq: 5,
- \(dqlimitBandwidthInLan\(dq: false,
- \(dqminHomeDiskFree\(dq: {
- \(dqvalue\(dq: 1,
- \(dqunit\(dq: \(dq%\(dq
- },
- \(dqreleasesURL\(dq: \(dqhttps://upgrades.syncthing.net/meta.json\(dq,
- \(dqalwaysLocalNets\(dq: [],
- \(dqoverwriteRemoteDeviceNamesOnConnect\(dq: false,
- \(dqtempIndexMinBlocks\(dq: 10,
- \(dqunackedNotificationIDs\(dq: [
- \(dqauthenticationUserAndPassword\(dq
- ],
- \(dqtrafficClass\(dq: 0,
- \(dqsetLowPriority\(dq: true,
- \(dqmaxFolderConcurrency\(dq: 0,
- \(dqcrURL\(dq: \(dqhttps://crash.syncthing.net/newcrash\(dq,
- \(dqcrashReportingEnabled\(dq: true,
- \(dqstunKeepaliveStartS\(dq: 180,
- \(dqstunKeepaliveMinS\(dq: 20,
- \(dqstunServers\(dq: [
- \(dqdefault\(dq
- ],
- \(dqdatabaseTuning\(dq: \(dqauto\(dq,
- \(dqmaxConcurrentIncomingRequestKiB\(dq: 0,
- \(dqannounceLANAddresses\(dq: true,
- \(dqsendFullIndexOnUpgrade\(dq: false,
- \(dqfeatureFlags\(dq: [],
- \(dqconnectionLimitEnough\(dq: 0,
- \(dqconnectionLimitMax\(dq: 0,
- \(dqinsecureAllowOldTLSVersions\(dq: false
- },
- \(dqremoteIgnoredDevices\(dq: [
- {
- \(dqtime\(dq: \(dq2022\-01\-09T20:02:01Z\(dq,
- \(dqdeviceID\(dq: \(dq...\(dq,
- \(dqname\(dq: \(dq...\(dq,
- \(dqaddress\(dq: \(dq192.168.0.20:22000\(dq
- }
- ],
- \(dqdefaults\(dq: {
- \(dqfolder\(dq: {
- \(dqid\(dq: \(dq\(dq,
- \(dqlabel\(dq: \(dq\(dq,
- \(dqfilesystemType\(dq: \(dqbasic\(dq,
- \(dqpath\(dq: \(dq~\(dq,
- \(dqtype\(dq: \(dqsendreceive\(dq,
- \(dqdevices\(dq: [
- {
- \(dqdeviceID\(dq: \(dq...\(dq,
- \(dqintroducedBy\(dq: \(dq\(dq,
- \(dqencryptionPassword\(dq: \(dq\(dq
- }
- ],
- \(dqrescanIntervalS\(dq: 3600,
- \(dqfsWatcherEnabled\(dq: true,
- \(dqfsWatcherDelayS\(dq: 10,
- \(dqignorePerms\(dq: false,
- \(dqautoNormalize\(dq: true,
- \(dqminDiskFree\(dq: {
- \(dqvalue\(dq: 1,
- \(dqunit\(dq: \(dq%\(dq
- },
- \(dqversioning\(dq: {
- \(dqtype\(dq: \(dq\(dq,
- \(dqparams\(dq: {},
- \(dqcleanupIntervalS\(dq: 3600,
- \(dqfsPath\(dq: \(dq\(dq,
- \(dqfsType\(dq: \(dqbasic\(dq
- },
- \(dqcopiers\(dq: 0,
- \(dqpullerMaxPendingKiB\(dq: 0,
- \(dqhashers\(dq: 0,
- \(dqorder\(dq: \(dqrandom\(dq,
- \(dqignoreDelete\(dq: false,
- \(dqscanProgressIntervalS\(dq: 0,
- \(dqpullerPauseS\(dq: 0,
- \(dqmaxConflicts\(dq: 10,
- \(dqdisableSparseFiles\(dq: false,
- \(dqdisableTempIndexes\(dq: false,
- \(dqpaused\(dq: false,
- \(dqweakHashThresholdPct\(dq: 25,
- \(dqmarkerName\(dq: \(dq.stfolder\(dq,
- \(dqcopyOwnershipFromParent\(dq: false,
- \(dqmodTimeWindowS\(dq: 0,
- \(dqmaxConcurrentWrites\(dq: 2,
- \(dqdisableFsync\(dq: false,
- \(dqblockPullOrder\(dq: \(dqstandard\(dq,
- \(dqcopyRangeMethod\(dq: \(dqstandard\(dq,
- \(dqcaseSensitiveFS\(dq: false,
- \(dqjunctionsAsDirs\(dq: false
- },
- \(dqdevice\(dq: {
- \(dqdeviceID\(dq: \(dq\(dq,
- \(dqname\(dq: \(dq\(dq,
- \(dqaddresses\(dq: [
- \(dqdynamic\(dq
- ],
- \(dqcompression\(dq: \(dqmetadata\(dq,
- \(dqcertName\(dq: \(dq\(dq,
- \(dqintroducer\(dq: false,
- \(dqskipIntroductionRemovals\(dq: false,
- \(dqintroducedBy\(dq: \(dq\(dq,
- \(dqpaused\(dq: false,
- \(dqallowedNetworks\(dq: [],
- \(dqautoAcceptFolders\(dq: false,
- \(dqmaxSendKbps\(dq: 0,
- \(dqmaxRecvKbps\(dq: 0,
- \(dqignoredFolders\(dq: [],
- \(dqmaxRequestKiB\(dq: 0,
- \(dquntrusted\(dq: false,
- \(dqremoteGUIPort\(dq: 0
- }
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/system/config/insync (DEPRECATED)
- .sp
- Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use
- \fI\%/rest/config/restart\-required\fP instead.
- .sp
- Returns whether the config is in sync, i.e. whether the running
- configuration is the same as that on disk.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqconfigInSync\(dq: true
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/config (DEPRECATED)
- .sp
- Deprecated since version v1.12.0: This endpoint still works as before but is deprecated. Use \fI\%Config Endpoints\fP
- instead.
- .sp
- Post the full contents of the configuration, in the same format as returned by
- the corresponding GET request. When posting the configuration succeeds,
- the posted configuration is immediately applied, except for changes that require a restart. Query
- \fI\%/rest/config/restart\-required\fP to check if a restart is required.
- .sp
- This endpoint is the main point to control Syncthing, even if the change only
- concerns a very small part of the config: The usual workflow is to get the
- config, modify the needed parts and post it again.
- .SS GET /rest/system/connections
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Return format changed in versions 0.13.0, 1.19.0 and 1.23.0.
- .UNINDENT
- .UNINDENT
- .sp
- Returns the list of configured devices and some metadata associated
- with them. The list also contains the local device itself as not connected.
- .sp
- The connection types are \fBTCP (Client)\fP, \fBTCP (Server)\fP, \fBRelay (Client)\fP and \fBRelay (Server)\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqconnections\(dq: {
- \(dqDOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA\(dq: {
- \(dqaddress\(dq: \(dq\(dq,
- \(dqat\(dq: \(dq0001\-01\-01T00:00:00Z\(dq,
- \(dqclientVersion\(dq: \(dq\(dq,
- \(dqconnected\(dq: false,
- \(dqinBytesTotal\(dq: 0,
- \(dqisLocal\(dq: false,
- \(dqoutBytesTotal\(dq: 0,
- \(dqpaused\(dq: false,
- \(dqstartedAt\(dq: \(dq0001\-01\-01T00:00:00Z\(dq,
- \(dqtype\(dq: \(dq\(dq
- },
- \(dqUYGDMA4\-TPHOFO5\-2VQYDCC\-7CWX7XW\-INZINQT\-LE4B42N\-4JUZTSM\-IWCSXA4\(dq: {
- \(dqaddress\(dq: \(dq\(dq,
- \(dqat\(dq: \(dq0001\-01\-01T00:00:00Z\(dq,
- \(dqclientVersion\(dq: \(dq\(dq,
- \(dqconnected\(dq: false,
- \(dqinBytesTotal\(dq: 0,
- \(dqisLocal\(dq: false,
- \(dqoutBytesTotal\(dq: 0,
- \(dqpaused\(dq: false,
- \(dqstartedAt\(dq: \(dq0001\-01\-01T00:00:00Z\(dq,
- \(dqtype\(dq: \(dq\(dq
- },
- \(dqYZJBJFX\-RDBL7WY\-6ZGKJ2D\-4MJB4E7\-ZATSDUY\-LD6Y3L3\-MLFUYWE\-AEMXJAC\(dq: {
- \(dqaddress\(dq: \(dq127.0.0.1:22002\(dq,
- \(dqat\(dq: \(dq2015\-11\-07T17:29:47.691548971+01:00\(dq,
- \(dqclientVersion\(dq: \(dqv0.12.1\(dq,
- \(dqconnected\(dq: true,
- \(dqinBytesTotal\(dq: 556,
- \(dqisLocal\(dq: true,
- \(dqoutBytesTotal\(dq: 550,
- \(dqpaused\(dq: false,
- \(dqstartedAt\(dq: \(dq2015\-11\-07T00:09:47Z\(dq,
- \(dqtype\(dq: \(dqTCP (Client)\(dq
- }
- },
- \(dqtotal\(dq: {
- \(dqat\(dq: \(dq2015\-11\-07T17:29:47.691637262+01:00\(dq,
- \(dqinBytesTotal\(dq: 1479,
- \(dqoutBytesTotal\(dq: 1318
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/system/debug
- .sp
- Added in version 0.12.0.
- .sp
- Returns the set of debug facilities and which of them are currently enabled.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqenabled\(dq: [
- \(dqbeacon\(dq
- ],
- \(dqfacilities\(dq: {
- \(dqbeacon\(dq: \(dqMulticast and broadcast discovery\(dq,
- \(dqconfig\(dq: \(dqConfiguration loading and saving\(dq,
- \(dqconnections\(dq: \(dqConnection handling\(dq,
- \(dqdb\(dq: \(dqThe database layer\(dq,
- \(dqdialer\(dq: \(dqDialing connections\(dq,
- \(dqdiscover\(dq: \(dqRemote device discovery\(dq,
- \(dqevents\(dq: \(dqEvent generation and logging\(dq,
- \(dqhttp\(dq: \(dqREST API\(dq,
- \(dqmain\(dq: \(dqMain package\(dq,
- \(dqmodel\(dq: \(dqThe root hub\(dq,
- \(dqprotocol\(dq: \(dqThe BEP protocol\(dq,
- \(dqrelay\(dq: \(dqRelay connection handling\(dq,
- \(dqscanner\(dq: \(dqFile change detection and hashing\(dq,
- \(dqstats\(dq: \(dqPersistent device and folder statistics\(dq,
- \(dqsync\(dq: \(dqMutexes\(dq,
- \(dqupgrade\(dq: \(dqBinary upgrades\(dq,
- \(dqupnp\(dq: \(dqUPnP discovery and port mapping\(dq,
- \(dqversioner\(dq: \(dqFile versioning\(dq
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/debug
- .sp
- Added in version 0.12.0.
- .sp
- Enables or disables debugging for specified facilities. Give one or both of
- \fBenable\fP and \fBdisable\fP query parameters, with comma separated facility
- names. To disable debugging of the beacon and discovery packages, and enable it
- for config and db:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-H X\-API\-Key:abc123 \-X POST \(aqhttp://localhost:8384/rest/system/debug?disable=beacon,discovery&enable=config,db\(aq
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/system/discovery
- .sp
- Returns the contents of the local discovery cache.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqLGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\(dq: [
- \(dq192.162.129.11:22000\(dq
- ]
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/discovery
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Removed in v0.12.0.
- .UNINDENT
- .UNINDENT
- .sp
- Post with the query parameters \fBdevice\fP and \fBaddr\fP to add entries to
- the discovery cache.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
- # Or with the X\-API\-Key header:
- curl \-X POST \-\-header \(dqX\-API\-Key: TcE28kVPdtJ8COws1JdM0b2nodj77WeQ\(dq http://127.0.0.1:8384/rest/system/discovery?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\e&addr=192.162.129.11:22000
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/error/clear
- .sp
- Post with empty to body to remove all recent errors.
- .SS GET /rest/system/error
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Return format changed in 0.12.0.
- .UNINDENT
- .UNINDENT
- .sp
- Returns the list of recent errors.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqerrors\(dq: [
- {
- \(dqwhen\(dq: \(dq2014\-09\-18T12:59:26.549953186+02:00\(dq,
- \(dqmessage\(dq: \(dqThis is an error string\(dq
- }
- ]
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/error
- .sp
- Post with an error message in the body (plain text) to register a new
- error. The new error will be displayed on any active GUI clients.
- .SS GET /rest/system/log
- .sp
- Added in version 0.12.0.
- .sp
- Returns the list of recent log entries. The optional \fBsince\fP parameter limits
- the results to message newer than the given timestamp in \X'tty: link https://datatracker.ietf.org/doc/html/rfc3339.html'\fI\%RFC 3339\fP <\fBhttps://datatracker.ietf.org/doc/html/rfc3339.html\fP>\X'tty: link' format.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqmessages\(dq: [
- {
- \(dqwhen\(dq: \(dq2014\-09\-18T12:59:26.549953186+02:00\(dq,
- \(dqmessage\(dq: \(dqThis is a log entry\(dq
- }
- ]
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/system/log.txt
- .sp
- Returns the same information, formatted as a text log instead of a JSON object.
- .SS GET /rest/system/paths
- .sp
- Added in version 1.21.0.
- .sp
- Returns the path locations used internally for storing configuration, database,
- and others.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqauditLog\(dq: \(dq/home/user/.local/share/syncthing/audit\-${timestamp}.log\(dq,
- \(dqbaseDir\-config\(dq: \(dq/home/user/.config/syncthing\(dq,
- \(dqbaseDir\-data\(dq: \(dq/home/user/.local/share/syncthing\(dq,
- \(dqbaseDir\-userHome\(dq: \(dq/home/user\(dq,
- \(dqcertFile\(dq: \(dq/home/user/.config/syncthing/cert.pem\(dq,
- \(dqconfig\(dq: \(dq/home/user/.config/syncthing/config.xml\(dq,
- \(dqcsrfTokens\(dq: \(dq/home/user/.config/syncthing/csrftokens.txt\(dq,
- \(dqdatabase\(dq: \(dq/home/user/.local/share/syncthing/index\-v0.14.0.db\(dq,
- \(dqdefFolder\(dq: \(dq/home/user/Sync\(dq,
- \(dqguiAssets\(dq: \(dq/home/user/src/syncthing/gui\(dq,
- \(dqhttpsCertFile\(dq: \(dq/home/user/.config/syncthing/https\-cert.pem\(dq,
- \(dqhttpsKeyFile\(dq: \(dq/home/user/.config/syncthing/https\-key.pem\(dq,
- \(dqkeyFile\(dq: \(dq/home/user/.config/syncthing/key.pem\(dq,
- \(dqlogFile\(dq: \(dq\-\(dq,
- \(dqpanicLog\(dq: \(dq/home/user/.local/share/syncthing/panic\-${timestamp}.log\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/pause
- .sp
- Pause the given device or all devices.
- .sp
- Takes the optional parameter \fBdevice\fP (device ID). When omitted,
- pauses all devices. Returns status 200 and no content upon success, or status
- 500 and a plain text error on failure.
- .SS GET /rest/system/ping
- .sp
- Returns a \fB{\(dqping\(dq: \(dqpong\(dq}\fP object.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqping\(dq: \(dqpong\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/ping
- .sp
- Returns a \fB{\(dqping\(dq: \(dqpong\(dq}\fP object.
- .SS POST /rest/system/reset
- .sp
- Post with empty body to erase the current index database and restart
- Syncthing. With no query parameters, the entire database is erased from disk.
- By specifying the \fBfolder\fP parameter with a valid folder ID, only
- information for that folder will be erased:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST \-H \(dqX\-API\-Key: abc123\(dq http://localhost:8384/rest/system/reset?folder=ab1c2\-def3g
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- \fBCaution\fP: See \fI\%\-\-reset\-database\fP for \fB\&.stfolder\fP creation
- side\-effect and caution regarding mountpoints.
- .SS POST /rest/system/restart
- .sp
- Post with empty body to immediately restart Syncthing.
- .SS POST /rest/system/resume
- .sp
- Resume the given device or all devices.
- .sp
- Takes the optional parameter \fBdevice\fP (device ID). When omitted,
- resumes all devices. Returns status 200 and no content upon success, or status
- 500 and a plain text error on failure.
- .SS POST /rest/system/shutdown
- .sp
- Post with empty body to cause Syncthing to exit and not restart.
- .SS GET /rest/system/status
- .sp
- Returns information about current system status and resource usage. The CPU percent value has been deprecated from the API and will always report 0.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqalloc\(dq: 30618136,
- \(dqconnectionServiceStatus\(dq: {
- \(dqdynamic+https://relays.syncthing.net/endpoint\(dq: {
- \(dqerror\(dq: null,
- \(dqlanAddresses\(dq: [
- \(dqrelay://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\(dq
- ],
- \(dqwanAddresses\(dq: [
- \(dqrelay://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\(dq
- ]
- },
- \(dqtcp://0.0.0.0:22000\(dq: {
- \(dqerror\(dq: null,
- \(dqlanAddresses\(dq: [
- \(dqtcp://0.0.0.0:22000\(dq
- ],
- \(dqwanAddresses\(dq: [
- \(dqtcp://0.0.0.0:22000\(dq
- ]
- }
- },
- \(dqcpuPercent\(dq: 0,
- \(dqdiscoveryEnabled\(dq: true,
- \(dqdiscoveryErrors\(dq: {
- \(dqglobal@https://discovery\-v4\-1.syncthing.net/v2/\(dq: \(dq500 Internal Server Error\(dq,
- \(dqglobal@https://discovery\-v4\-2.syncthing.net/v2/\(dq: \(dqPost https://discovery\-v4\-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)\(dq,
- \(dqglobal@https://discovery\-v4\-3.syncthing.net/v2/\(dq: \(dqPost https://discovery\-v4\-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)\(dq,
- \(dqglobal@https://discovery\-v6\-1.syncthing.net/v2/\(dq: \(dqPost https://discovery\-v6\-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host\(dq,
- \(dqglobal@https://discovery\-v6\-2.syncthing.net/v2/\(dq: \(dqPost https://discovery\-v6\-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host\(dq,
- \(dqglobal@https://discovery\-v6\-3.syncthing.net/v2/\(dq: \(dqPost https://discovery\-v6\-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host\(dq
- },
- \(dqdiscoveryStatus\(dq: {
- \(dqIPv4 local\(dq: {
- \(dqerror\(dq: null
- },
- \(dqIPv6 local\(dq: {
- \(dqerror\(dq: null
- },
- \(dqglobal@https://discovery\-v4\-1.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dq500 Internal Server Error\(dq
- },
- \(dqglobal@https://discovery\-v4\-2.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dqPost https://discovery\-v4\-2.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)\(dq
- },
- \(dqglobal@https://discovery\-v4\-3.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dqPost https://discovery\-v4\-3.syncthing.net/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)\(dq
- },
- \(dqglobal@https://discovery\-v6\-1.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dqPost https://discovery\-v6\-1.syncthing.net/v2/: dial tcp [2001:470:28:4d6::5]:443: connect: no route to host\(dq
- },
- \(dqglobal@https://discovery\-v6\-2.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dqPost https://discovery\-v6\-2.syncthing.net/v2/: dial tcp [2604:a880:800:10::182:a001]:443: connect: no route to host\(dq
- },
- \(dqglobal@https://discovery\-v6\-3.syncthing.net/v2/\(dq: {
- \(dqerror\(dq: \(dqPost https://discovery\-v6\-3.syncthing.net/v2/: dial tcp [2400:6180:0:d0::d9:d001]:443: connect: no route to host\(dq
- }
- },
- \(dqdiscoveryMethods\(dq: 8,
- \(dqgoroutines\(dq: 49,
- \(dqlastDialStatus\(dq: {
- \(dqtcp://10.20.30.40\(dq: {
- \(dqwhen\(dq: \(dq2019\-05\-16T07:41:23Z\(dq,
- \(dqerror\(dq: \(dqdial tcp 10.20.30.40:22000: i/o timeout\(dq
- },
- \(dqtcp://172.16.33.3:22000\(dq: {
- \(dqwhen\(dq: \(dq2019\-05\-16T07:40:43Z\(dq,
- \(dqok\(dq: true
- },
- \(dqtcp://83.233.120.221:22000\(dq: {
- \(dqwhen\(dq: \(dq2019\-05\-16T07:41:13Z\(dq,
- \(dqerror\(dq: \(dqdial tcp 83.233.120.221:22000: connect: connection refused\(dq
- }
- },
- \(dqmyID\(dq: \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq,
- \(dqpathSeparator\(dq: \(dq/\(dq,
- \(dqstartTime\(dq: \(dq2016\-06\-06T19:41:43.039284753+02:00\(dq,
- \(dqsys\(dq: 42092792,
- \(dqthemes\(dq: [
- \(dqdefault\(dq,
- \(dqdark\(dq
- ],
- \(dqtilde\(dq: \(dq/Users/jb\(dq,
- \(dquptime\(dq: 2635
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Added in version 1.2.0: The \fBlastDialStatus\fP dictionary contains the last error (or \fBnull\fP for
- success) for each peer address that Syncthing has attempted to contact.
- The \fBconnectionServiceStatus\fP entries gained \fB\(dqerror\(dq: null\fP
- attributes where previously there would be no \fBerror\fP attribute at all
- in the success case.
- .sp
- Added in version 1.18.0: The \fBdiscoveryStatus\fP dictionary lists all configured discovery methods, not
- only failed ones like the now deprecated \fBdiscoveryErrors\fP\&. Each entry is
- an object itself (for consistency with other fields), where a \fBnull\fP value
- for the \fBerror\fP attribute means the method is running successfully. This
- effectively deprecates the \fBdiscoveryMethods\fP attribute as well, which now
- always matches the number of entries in \fBdiscoveryStatus\fP\&.
- .SS GET /rest/system/upgrade
- .sp
- Checks for a possible upgrade and returns an object describing the
- newest version and upgrade possibility.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqlatest\(dq: \(dqv0.14.47\(dq,
- \(dqmajorNewer\(dq: false,
- \(dqnewer\(dq: true,
- \(dqrunning\(dq: \(dqv0.14.46\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/system/upgrade
- .sp
- Perform an upgrade to the newest released version and restart. Does
- nothing if there is no newer version than currently running.
- .SS GET /rest/system/version
- .sp
- Returns the current Syncthing version information.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqarch\(dq: \(dqamd64\(dq,
- \(dqlongVersion\(dq: \(dqsyncthing v0.10.27+3\-gea8c3de (go1.4 darwin\-amd64 default) jb@syno 2015\-03\-16 11:01:29 UTC\(dq,
- \(dqos\(dq: \(dqdarwin\(dq,
- \(dqversion\(dq: \(dqv0.10.27+3\-gea8c3de\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SH CONFIG ENDPOINTS
- .SS Config Endpoints
- .sp
- Added in version 1.12.0.
- .sp
- These endpoints facilitate access and modification of the \fI\%configuration\fP in a granular way. Config sent to the endpoints must be in the
- same format as returned by the corresponding GET request. When posting the
- configuration succeeds, the posted configuration is immediately applied, except
- for changes that require a restart. Query \fI\%/rest/config/restart\-required\fP to check if
- a restart is required.
- .sp
- For all endpoints supporting \fBPATCH\fP, it takes the existing config and
- unmarshals the given JSON object on top of it. This means all child objects will
- replace the existing objects, not extend them. For example for
- \fBRawListenAddresses\fP in options, which is an array of strings, sending
- \fB{RawListenAddresses: [\(dqtcp://10.0.0.2\(dq]}\fP will replace all existing listen
- addresses.
- .SS /rest/config
- .sp
- \fBGET\fP returns the entire config and \fBPUT\fP replaces it.
- .SS /rest/config/restart\-required
- .sp
- \fBGET\fP returns whether a restart of Syncthing is required for the current
- config to take effect.
- .SS /rest/config/folders, /rest/config/devices
- .sp
- \fBGET\fP returns all folders respectively devices as an array. \fBPUT\fP takes an array and
- \fBPOST\fP a single object. In both cases if a given folder/device already exists,
- it’s replaced, otherwise a new one is added.
- .SS /rest/config/folders/*id*, /rest/config/devices/*id*
- .sp
- Put the desired folder\- respectively device\-ID in place of *id*. \fBGET\fP
- returns the folder/device for the given ID, \fBPUT\fP replaces the entire config,
- \fBPATCH\fP replaces only the given child objects and \fBDELETE\fP removes the
- folder/device.
- .SS /rest/config/defaults/folder, /rest/config/defaults/device
- .sp
- \fBGET\fP returns a template folder / device configuration object with all default
- values, which only needs a unique ID to be applied. \fBPUT\fP replaces the
- default config (omitted values are reset to the hard\-coded defaults), \fBPATCH\fP
- replaces only the given child objects.
- .SS /rest/config/defaults/ignores
- .sp
- Added in version 1.19.0.
- .sp
- \fBGET\fP returns an object with a single \fBlines\fP attribute listing ignore
- patterns to be used by default on folders, as an array of single\-line strings.
- \fBPUT\fP replaces the default ignore patterns from an object of the same format.
- .SS /rest/config/options, /rest/config/ldap, /rest/config/gui
- .sp
- \fBGET\fP returns the respective object, \fBPUT\fP replaces the entire object and
- \fBPATCH\fP replaces only the given child objects.
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- The \fI\%gui.password\fP configuration option has special handling to
- accept already hashed passwords. Any valid bcrypt hash is stored verbatim,
- while a plaintext password is first hashed.
- .UNINDENT
- .UNINDENT
- .SH CLUSTER ENDPOINTS
- .sp
- Concerns the mesh network structure.
- .SS DELETE /rest/cluster/pending/devices
- .sp
- Added in version 1.18.0.
- .sp
- Remove records about a pending remote device which tried to connect. Valid
- values for the \fBdevice\fP parameter are those from the corresponding
- \fI\%GET /rest/cluster/pending/devices\fP endpoint.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-X DELETE \-H \(dqX\-API\-Key: abc123\(dq http://localhost:8384/rest/cluster/pending/devices?device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Returns status 200 and no content upon success, or status 500 and a
- plain text error on failure. A \fI\%PendingDevicesChanged\fP
- event will be generated in response.
- .sp
- For a more permanent effect, also for future connections from the same
- device ID, the device should be ignored in the \fI\%configuration\fP instead.
- .SS GET /rest/cluster/pending/devices
- .sp
- Added in version 1.13.0.
- .sp
- Lists remote devices which have tried to connect, but are not yet
- configured in our instance.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq: {
- \(dqtime\(dq: \(dq2020\-03\-18T11:43:07Z\(dq,
- \(dqname\(dq: \(dqFriend Joe\(dq,
- \(dqaddress\(dq: \(dq192.168.1.2:22000\(dq
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS DELETE /rest/cluster/pending/folders
- .sp
- Added in version 1.18.0.
- .sp
- Remove records about a pending folder announced from a remote device. Valid
- values for the \fBfolder\fP and \fBdevice\fP parameters are those from the
- corresponding \fI\%GET /rest/cluster/pending/folders\fP endpoint. The \fBdevice\fP
- parameter is optional and affects announcements of this folder from the given
- device, or from \fIany\fP device if omitted.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-X DELETE \-H \(dqX\-API\-Key: abc123\(dq http://localhost:8384/rest/cluster/pending/folders?folder=cpkn4\-57ysy&device=P56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Returns status 200 and no content upon success, or status 500 and a plain text
- error on failure. A \fI\%PendingFoldersChanged\fP event will be
- generated in response.
- .sp
- For a more permanent effect, also for future announcements of the same folder
- ID, the folder should be ignored in the \fI\%configuration\fP
- instead.
- .SS GET /rest/cluster/pending/folders
- .sp
- Added in version 1.13.0.
- .sp
- Lists folders which remote devices have offered to us, but are not yet
- shared from our instance to them. Takes the optional \fBdevice\fP
- parameter to only return folders offered by a specific remote device.
- Other offering devices are also omitted from the result.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqcpkn4\-57ysy\(dq: {
- \(dqofferedBy\(dq: {
- \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq: {
- \(dqtime\(dq: \(dq2020\-03\-18T11:43:07Z\(dq,
- \(dqlabel\(dq: \(dqJoe\(aqs folder\(dq,
- \(dqreceiveEncrypted\(dq: true,
- \(dqremoteEncrypted\(dq: false
- },
- \(dqDOVII4U\-SQEEESM\-VZ2CVTC\-CJM4YN5\-QNV7DCU\-5U3ASRL\-YVFG6TH\-W5DV5AA\(dq: {
- \(dqtime\(dq: \(dq2020\-03\-01T10:12:13Z\(dq,
- \(dqlabel\(dq: \(dqJane\(aqs and Joe\(aqs folder\(dq,
- \(dqreceiveEncrypted\(dq: false,
- \(dqremoteEncrypted\(dq: false
- }
- }
- },
- \(dqabcde\-fghij\(dq: {
- \(dqofferedBy\(dq: {
- \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq: {
- \(dqtime\(dq: \(dq2020\-03\-18T11:43:07Z\(dq,
- \(dqlabel\(dq: \(dqMyPics\(dq,
- \(dqreceiveEncrypted\(dq: false,
- \(dqremoteEncrypted\(dq: false
- }
- }
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SH FOLDER ENDPOINTS
- .sp
- Runtime state of the individual shared folders.
- .SS GET /rest/folder/errors
- .sp
- Added in version 0.14.53.
- .sp
- Takes one mandatory parameter, \fBfolder\fP, and returns the list of errors
- encountered during scanning or pulling.
- .sp
- The results can be paginated using the \fI\%common pagination parameters\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqfolder\(dq: \(dqnnhic\-sxuae\(dq,
- \(dqerrors\(dq: [
- {
- \(dqpath\(dq: \(dqnoperm.txt\(dq,
- \(dqerror\(dq: \(dqhashing: open /path/to/folder/noperm.txt: permission denied\(dq
- }
- ],
- \(dqpage\(dq: 1,
- \(dqperpage\(dq: 100
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/folder/pullerrors (DEPRECATED)
- .sp
- Deprecated since version v0.14.53: This endpoint still works as before but is deprecated. Use
- \fI\%GET /rest/folder/errors\fP instead, which returns the same information.
- .sp
- See \X'tty: link https://github.com/syncthing/syncthing/commit/d510e3cca3d5caae42121fa206b3decc981ae59e'\fI\%https://github.com/syncthing/syncthing/commit/d510e3cca3d5caae42121fa206b3decc981ae59e\fP\X'tty: link'
- .SS GET /rest/folder/versions
- .sp
- Added in version 0.14.44.
- .sp
- Takes one mandatory parameter, \fBfolder\fP, and returns the list of archived
- files that could be recovered. How many versions are available depends on the
- \fI\%File Versioning\fP configuration. Each entry specifies when the file
- version was archived as the \fBversionTime\fP, the \fBmodTime\fP when it was last
- modified before being archived, and the size in bytes.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqdir1/dir2/bar\(dq: [
- {
- \(dqversionTime\(dq: \(dq2022\-02\-06T20:44:12+01:00\(dq,
- \(dqmodTime\(dq: \(dq2021\-01\-14T13:21:22+01:00\(dq,
- \(dqsize\(dq: 4
- }
- ],
- \(dqbaz\(dq: [
- {
- \(dqversionTime\(dq: \(dq2022\-02\-06T20:44:20+01:00\(dq,
- \(dqmodTime\(dq: \(dq2021\-01\-14T13:23:49+01:00\(dq,
- \(dqsize\(dq: 4
- }
- ],
- \(dqfoo\(dq: [
- {
- \(dqversionTime\(dq: \(dq2022\-02\-06T20:55:31+01:00\(dq,
- \(dqmodTime\(dq: \(dq2022\-02\-06T20:44:13+01:00\(dq,
- \(dqsize\(dq: 4
- },
- {
- \(dqversionTime\(dq: \(dq2022\-02\-06T20:44:20+01:00\(dq,
- \(dqmodTime\(dq: \(dq2021\-01\-14T13:21:16+01:00\(dq,
- \(dqsize\(dq: 4
- }
- ]
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/folder/versions
- .sp
- Restore archived versions of a given set of files. Expects an object with
- attributes named after the relative file paths, with timestamps as values
- matching valid \fBversionTime\fP entries in the corresponding
- \fI\%GET /rest/folder/versions\fP response object.
- .sp
- Takes the mandatory parameter \fBfolder\fP (folder ID). Returns an object
- containing any error messages that occurred during restoration of the file, with
- the file path as attribute name.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST \-H X\-API\-key:... http://127.0.0.1:8384/rest/folder/versions?folder=default \-d \(aq{
- \(dqdir1/dir2/bar\(dq: \(dq2022\-02\-06T20:44:12+01:00\(dq,
- \(dqbaz\(dq: \(dq2022\-02\-06T20:44:20+01:00\(dq
- }\(aq
- .EE
- .UNINDENT
- .UNINDENT
- .SH DATABASE ENDPOINTS
- .SS GET /rest/db/browse
- .sp
- Returns the directory tree of the global model. Directories are always
- JSON objects (map/dictionary), and files are always arrays of
- modification time and size. The first integer is the files modification
- time, and the second integer is the file size.
- .sp
- The call takes one mandatory \fBfolder\fP parameter and two optional
- parameters. Optional parameter \fBlevels\fP defines how deep within the
- tree we want to dwell down (0 based, defaults to unlimited depth)
- Optional parameter \fBprefix\fP defines a prefix within the tree where to
- start building the structure.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-s http://localhost:8384/rest/db/browse?folder=j663y\-3ct3e&prefix=DCIM&levels=2
- [
- {
- \(dqmodTime\(dq : \(dq2020\-10\-02T23:48:52.076996974+02:00\(dq,
- \(dqname\(dq : \(dq100ANDRO\(dq,
- \(dqsize\(dq : 128,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_DIRECTORY\(dq
- },
- {
- \(dqchildren\(dq : [
- {
- \(dqmodTime\(dq : \(dq2020\-12\-16T23:31:34.5009668+01:00\(dq,
- \(dqname\(dq : \(dqIMG_20201114_124821.jpg\(dq,
- \(dqsize\(dq : 10682189,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_FILE\(dq
- },
- {
- \(dqmodTime\(dq : \(dq2020\-12\-16T23:31:35.0106367+01:00\(dq,
- \(dqname\(dq : \(dqIMG_20201213_122451.jpg\(dq,
- \(dqsize\(dq : 7936351,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_FILE\(dq
- },
- {
- \(dqmodTime\(dq : \(dq2020\-12\-13T12:25:05.017097469+01:00\(dq,
- \(dqname\(dq : \(dqIMG_20201213_122504.jpg\(dq,
- \(dqsize\(dq : 8406507,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_FILE\(dq
- },
- {
- \(dqmodTime\(dq : \(dq2020\-12\-13T12:25:06.127097469+01:00\(dq,
- \(dqname\(dq : \(dqIMG_20201213_122505.jpg\(dq,
- \(dqsize\(dq : 8381931,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_FILE\(dq
- },
- {
- \(dqmodTime\(dq : \(dq2020\-12\-13T12:53:29.707298401+01:00\(dq,
- \(dqname\(dq : \(dqIMG_20201213_125329.jpg\(dq,
- \(dqsize\(dq : 4388331,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_FILE\(dq
- },
- ],
- \(dqmodTime\(dq : \(dq2020\-10\-09T13:04:42.4410738+02:00\(dq,
- \(dqname\(dq : \(dqCamera\(dq,
- \(dqsize\(dq : 128,
- \(dqtype\(dq : \(dqFILE_INFO_TYPE_DIRECTORY\(dq
- },
- ]
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
- .UNINDENT
- .UNINDENT
- .SS GET /rest/db/completion
- .sp
- Returns the completion percentage (0 to 100) and byte / item counts. Takes
- optional \fBdevice\fP and \fBfolder\fP parameters:
- .INDENT 0.0
- .IP \(bu 2
- \fBfolder\fP specifies the folder ID to calculate completion for. An empty
- or absent \fBfolder\fP parameter means all folders as an aggregate.
- .IP \(bu 2
- \fBdevice\fP specifies the device ID to calculate completion for. An empty
- or absent \fBdevice\fP parameter means the local device.
- .UNINDENT
- .sp
- If a device is specified but no folder, completion is calculated for all
- folders shared with that device.
- .SS Example Queries
- .sp
- Completion status for folder \fBabcd\-1234\fP on device \fBI6KAH76\-...\-3PSROAU\fP:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- /rest/db/completion?folder=abcd\-1234&device=I6KAH76\-...\-3PSROAU
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Aggregated completion status for device \fBI6KAH76\-...\-3PSROAU\fP (all folders shared with them):
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- /rest/db/completion?device=I6KAH76\-...\-3PSROAU
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Completion status for folder \fBabcd\-1234\fP on the local device:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- /rest/db/completion?folder=abcd\-1234
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Aggregated completion status for all folders on the local device:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- /rest/db/completion
- .EE
- .UNINDENT
- .UNINDENT
- .SS Example Response
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqcompletion\(dq: 99.9937565835,
- \(dqglobalBytes\(dq: 156793013575,
- \(dqneedBytes\(dq: 9789241,
- \(dqglobalItems\(dq: 7823,
- \(dqneedItems\(dq: 412,
- \(dqneedDeletes\(dq: 0,
- \(dqremoteState\(dq: \(dqvalid\(dq,
- \(dqsequence\(dq: 12
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Added in version 1.8.0: The ability to aggregate multiple folders by leaving out the folder ID.
- Querying data for the local device by leaving out the device ID. Returning
- the \fBglobalItems\fP counter in the response.
- .sp
- Added in version 1.20.0: Indication whether the remote device has accepted the folder (shares it with
- us) as well, and whether it is paused. The \fBremoteState\fP field is
- meaningless for aggregated responses, \fBunknown\fP when the remote device is
- not connected. Otherwise it can be either \fBpaused\fP, \fBnotSharing\fP, or
- \fBvalid\fP if the remote is sharing back.
- .SS GET /rest/db/file
- .sp
- Returns most data available about a given file, including version and
- availability. Takes \fBfolder\fP and \fBfile\fP parameters. \fBlocal\fP and
- \fBglobal\fP refer to the current file on disk and the globally newest file,
- respectively.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqavailability\(dq: [
- {
- \(dqid\(dq: \(dqITZRNXE\-YNROGBZ\-HXTH5P7\-VK5NYE5\-QHRQGE2\-7JQ6VNJ\-KZUEDIU\-5PPR5AM\(dq,
- \(dqfromTemporary\(dq: false
- }
- ],
- \(dqglobal\(dq: { /* a file entry */ },
- \(dqlocal\(dq: { /* a file entry */ }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- A file entry looks like this:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- {
- \(dqdeleted\(dq: false,
- \(dqignored\(dq: false,
- \(dqinodeChange\(dq: \(dq1970\-01\-01T01:00:00+01:00\(dq,
- \(dqinvalid\(dq: false,
- \(dqlocalFlags\(dq: 0,
- \(dqmodified\(dq: \(dq2022\-09\-28T08:07:19.979723+02:00\(dq,
- \(dqmodifiedBy\(dq: \(dq523ITIE\(dq,
- \(dqmustRescan\(dq: false,
- \(dqname\(dq: \(dqimg\(dq,
- \(dqnoPermissions\(dq: false,
- \(dqnumBlocks\(dq: 0,
- \(dqpermissions\(dq: \(dq0755\(dq,
- \(dqplatform\(dq: { /* platform specific data */ },
- \(dqsequence\(dq: 914,
- \(dqsize\(dq: 128,
- \(dqtype\(dq: \(dqFILE_INFO_TYPE_DIRECTORY\(dq,
- \(dqversion\(dq: [
- \(dq523ITIE:1664345275\(dq
- ]
- },
- \(dqmtime\(dq: {
- \(dqerr\(dq: null,
- \(dqvalue\(dq: {
- \(dqreal\(dq: \(dq0001\-01\-01T00:00:00Z\(dq,
- \(dqvirtual\(dq: \(dq0001\-01\-01T00:00:00Z\(dq
- }
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Platform specific data may be ownership, extended attributes, etc. and is
- divided into entries per operating system / platform. An example platform
- entry containing ownership information for Unix systems and an extended
- attribute for macOS (“darwin”) looks as follows:
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqdarwin\(dq: {
- \(dqxattrs\(dq: [
- {
- \(dqname\(dq: \(dqnet.kastelo.xattrtest\(dq,
- \(dqvalue\(dq: \(dqaGVsbG8=\(dq
- }
- ]
- },
- \(dqfreebsd\(dq: null,
- \(dqlinux\(dq: null,
- \(dqnetbsd\(dq: null,
- \(dqunix\(dq: {
- \(dqgid\(dq: 20,
- \(dqgroupName\(dq: \(dqstaff\(dq,
- \(dqownerName\(dq: \(dqjb\(dq,
- \(dquid\(dq: 501
- },
- \(dqwindows\(dq: null
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/db/ignores
- .sp
- Takes one parameter, \fBfolder\fP, and returns the content of the
- \fB\&.stignore\fP as the \fBignore\fP field. A second field, \fBexpanded\fP,
- provides a list of strings which represent globbing patterns described by gobwas/glob (based on standard wildcards) that match the patterns in \fB\&.stignore\fP and all the includes. If appropriate these globs are prepended by the following modifiers: \fB!\fP to negate the glob, \fB(?i)\fP to do case insensitive matching and \fB(?d)\fP to enable removing of ignored files in an otherwise empty directory.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqignore\(dq: [
- \(dq(?i)/Backups\(dq
- ],
- \(dqexpanded\(dq: [
- \(dq(?i)Backups\(dq,
- \(dq(?i)Backups/**\(dq
- ]
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/db/ignores
- .sp
- Expects a format similar to the output of \fI\%GET /rest/db/ignores\fP call, but only
- containing the \fBignore\fP field (\fBexpanded\fP field should be omitted).
- It takes one parameter, \fBfolder\fP, and either updates the content of
- the \fB\&.stignore\fP echoing it back as a response, or returns an error.
- .SS GET /rest/db/localchanged
- .sp
- Added in version 0.14.55.
- .sp
- Takes one mandatory parameter, \fBfolder\fP, and returns the list of files which
- were changed locally in a receive\-only folder. Thus they differ from the global
- state and could be reverted by pulling from remote devices again, see
- \fI\%POST /rest/db/revert\fP\&.
- .sp
- The results can be paginated using the \fI\%common pagination parameters\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqfiles\(dq: [
- {
- \(dqflags\(dq: \(dq0755\(dq,
- \(dqsequence\(dq: 6,
- \(dqmodified\(dq: \(dq2015\-04\-20T23:06:12+09:00\(dq,
- \(dqname\(dq: \(dqls\(dq,
- \(dqsize\(dq: 34640,
- \(dqversion\(dq: [
- \(dq5157751870738175669:1\(dq
- ]
- }
- ],
- \(dqpage\(dq: 1,
- \(dqperpage\(dq: 100
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- This is an expensive call, increasing CPU and RAM usage on the device.
- Use sparingly.
- .UNINDENT
- .UNINDENT
- .SS GET /rest/db/need
- .sp
- Takes one mandatory parameter, \fBfolder\fP, and returns lists of files which are
- needed by this device in order for it to become in sync.
- .sp
- The results can be paginated using the \fI\%common pagination parameters\fP\&. Pagination happens, across the union of all needed files,
- that is \- across all 3 sections of the response. For example, given the current
- need state is as follows:
- .INDENT 0.0
- .IP 1. 3
- \fBprogress\fP has 15 items
- .IP 2. 3
- \fBqueued\fP has 3 items
- .IP 3. 3
- \fBrest\fP has 12 items
- .UNINDENT
- .sp
- If you issue a query with \fBpage=1\fP and \fBperpage=10\fP, only the \fBprogress\fP
- section in the response will have 10 items. If you issue a request query with
- \fBpage=2\fP and \fBperpage=10\fP, \fBprogress\fP section will have the last 5 items,
- \fBqueued\fP section will have all 3 items, and \fBrest\fP section will have first
- 2 items. If you issue a query for \fBpage=3\fP and \fBperpage=10\fP, you will only
- have the last 10 items of the \fBrest\fP section.
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- Return format changed in version 0.14.43, removing the \fBtotal\fP count
- attribute.
- .UNINDENT
- .UNINDENT
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- # Files currently being downloaded
- \(dqprogress\(dq: [
- {
- \(dqflags\(dq: \(dq0755\(dq,
- \(dqsequence\(dq: 6,
- \(dqmodified\(dq: \(dq2015\-04\-20T23:06:12+09:00\(dq,
- \(dqname\(dq: \(dqls\(dq,
- \(dqsize\(dq: 34640,
- \(dqversion\(dq: [
- \(dq5157751870738175669:1\(dq
- ]
- }
- ],
- # Files queued to be downloaded next (as per array order)
- \(dqqueued\(dq: [
- ...
- ],
- # Files to be downloaded after all queued files will be downloaded.
- # This happens when we start downloading files, and new files get added while we are downloading.
- \(dqrest\(dq: [
- ...
- ],
- \(dqpage\(dq: 1,
- \(dqperpage\(dq: 100
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- This is an expensive call, increasing CPU and RAM usage on the device.
- Use sparingly.
- .UNINDENT
- .UNINDENT
- .SS POST /rest/db/override
- .sp
- Request override of a send only folder. Override means to make the local
- version latest, overriding changes made on other devices. This API call does
- nothing if the folder is not a send only folder.
- .sp
- Takes the mandatory parameter \fIfolder\fP (folder ID).
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST \-H X\-API\-key:... http://127.0.0.1:8384/rest/db/override?folder=default
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/db/prio
- .sp
- Moves the file to the top of the download queue.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- Response contains the same output as \fI\%GET /rest/db/need\fP\&.
- .SS GET /rest/db/remoteneed
- .sp
- Added in version 0.14.43.
- .sp
- Takes the mandatory parameters \fBfolder\fP and \fBdevice\fP, and returns the list
- of files which are needed by that remote device in order for it to become in
- sync with the shared folder.
- .sp
- The results can be paginated using the \fI\%common pagination parameters\fP\&.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqfiles\(dq: [
- {
- \(dqflags\(dq: \(dq0755\(dq,
- \(dqsequence\(dq: 6,
- \(dqmodified\(dq: \(dq2015\-04\-20T23:06:12+09:00\(dq,
- \(dqname\(dq: \(dqls\(dq,
- \(dqsize\(dq: 34640,
- \(dqversion\(dq: [
- \(dq5157751870738175669:1\(dq
- ]
- }
- ],
- \(dqpage\(dq: 1,
- \(dqperpage\(dq: 100
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- This is an expensive call, increasing CPU and RAM usage on the device.
- Use sparingly.
- .UNINDENT
- .UNINDENT
- .SS POST /rest/db/revert
- .sp
- Added in version 0.14.50.
- .sp
- Request revert of a receive only folder. Reverting a folder means to undo
- all local changes. This API call does nothing if the folder is not a receive
- only folder.
- .sp
- Takes the mandatory parameter \fIfolder\fP (folder ID).
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST \-H X\-API\-Key:... http://127.0.0.1:8384/rest/db/revert?folder=default
- .EE
- .UNINDENT
- .UNINDENT
- .SS POST /rest/db/scan
- .sp
- Request immediate scan. Takes the optional parameters \fBfolder\fP (folder ID),
- \fBsub\fP (path relative to the folder root) and \fBnext\fP (time in seconds). If
- \fBfolder\fP is omitted or empty all folders are scanned. If \fBsub\fP is given,
- only this path (and children, in case it’s a directory) is scanned. The \fBnext\fP
- argument delays Syncthing’s automated rescan interval for a given amount of
- seconds.
- .sp
- Requesting scan of a path that no longer exists, but previously did, is
- valid and will result in Syncthing noticing the deletion of the path in
- question.
- .sp
- Returns status 200 and no content upon success, or status 500 and a
- plain text error if an error occurred during scanning.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- curl \-X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/db/status
- .sp
- Returns information about the current status of a folder.
- .sp
- Parameters: \fBfolder\fP, the ID of a folder.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqglobalBytes\(dq: 0,
- \(dqglobalDeleted\(dq: 0,
- \(dqglobalDirectories\(dq: 0,
- \(dqglobalFiles\(dq: 0,
- \(dqglobalSymlinks\(dq: 0,
- \(dqglobalTotalItems\(dq: 0,
- \(dqignorePatterns\(dq: false,
- \(dqinSyncBytes\(dq: 0,
- \(dqinSyncFiles\(dq: 0,
- \(dqinvalid\(dq: \(dq\(dq,
- \(dqlocalBytes\(dq: 0,
- \(dqlocalDeleted\(dq: 0,
- \(dqlocalDirectories\(dq: 0,
- \(dqlocalFiles\(dq: 0,
- \(dqlocalSymlinks\(dq: 0,
- \(dqlocalTotalItems\(dq: 0,
- \(dqneedBytes\(dq: 0,
- \(dqneedDeletes\(dq: 0,
- \(dqneedDirectories\(dq: 0,
- \(dqneedFiles\(dq: 0,
- \(dqneedSymlinks\(dq: 0,
- \(dqneedTotalItems\(dq: 0,
- \(dqpullErrors\(dq: 0,
- \(dqreceiveOnlyChangedBytes\(dq: 0,
- \(dqreceiveOnlyChangedDeletes\(dq: 0,
- \(dqreceiveOnlyChangedDirectories\(dq: 0,
- \(dqreceiveOnlyChangedFiles\(dq: 0,
- \(dqreceiveOnlyChangedSymlinks\(dq: 0,
- \(dqreceiveOnlyTotalItems\(dq: 0,
- \(dqsequence\(dq: 0,
- \(dqstate\(dq: \(dqidle\(dq,
- \(dqstateChanged\(dq: \(dq2018\-08\-08T07:04:57.301064781+02:00\(dq,
- \(dqversion\(dq: 0
- }
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- The various fields have the following meaning:
- .INDENT 0.0
- .TP
- .B global*:
- Data in the cluster latest version.
- .TP
- .B inSync*:
- Data that is locally the same as the cluster latest version.
- .TP
- .B local*:
- Data that is locally present, regardless of whether it’s the same or different version as the cluster latest version.
- .TP
- .B need*:
- Data that is needed to become up to date with the cluster latest version (i.e., data that is out of sync).
- .TP
- .B receiveOnlyChanged*:
- Data that has changed locally in a receive only folder, and thus not been sent to the cluster.
- .TP
- .B invalid:
- Deprecated, always empty.
- .TP
- .B pullErrors:
- The number of files that failed to sync during the last sync operations.
- .TP
- .B sequence:
- The current folder sequence number.
- .TP
- .B state:
- The current folder state.
- .TP
- .B stateChanged:
- When the folder state last changed.
- .TP
- .B version:
- Deprecated, equivalent to the sequence number.
- .UNINDENT
- .sp
- \fBNOTE:\fP
- .INDENT 0.0
- .INDENT 3.5
- This is an expensive call, increasing CPU and RAM usage on the device. Use sparingly.
- .UNINDENT
- .UNINDENT
- .SH EVENT ENDPOINTS
- .SS GET /rest/events
- .sp
- To receive events, perform a HTTP GET of \fB/rest/events\fP\&.
- .sp
- To filter the event list, in effect creating a specific subscription for only
- the desired event types, add a parameter \fBevents=EventTypeA,EventTypeB,...\fP
- where the event types are any of the \fI\%Event Types\fP\&. If no filter is
- specified, all events \fIexcept\fP \fI\%LocalChangeDetected\fP and
- \fI\%RemoteChangeDetected\fP are included.
- .sp
- The optional parameter \fBsince=<lastSeenID>\fP sets the ID of the last event
- you’ve already seen. Syncthing returns a JSON encoded array of event objects,
- starting at the event just after the one with this last seen ID. The default
- value is 0, which returns all events. There is a limit to the number of events
- buffered, so if the rate of events is high or the time between polling calls is
- long some events might be missed. This can be detected by noting a discontinuity
- in the event IDs.
- .sp
- If no new events are produced since \fB<lastSeenID>\fP, the HTTP call blocks and
- waits for new events to happen before returning. If \fB<lastSeenID>\fP is a
- future ID, the HTTP call blocks until such ID is reached or timeouts. By
- default it times out after 60 seconds returning an empty array. The time out
- duration can be customized with the optional parameter \fBtimeout=<seconds>\fP\&.
- .sp
- To receive only a limited number of events, add the \fBlimit=<n>\fP parameter with a
- suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This
- can be used to catch up with the latest event ID after a disconnection for
- example: \fB/rest/events?since=0&limit=1\fP\&.
- .SS GET /rest/events/disk
- .sp
- This convenience endpoint provides the same event stream, but pre\-filtered to show
- only \fI\%LocalChangeDetected\fP and \fI\%RemoteChangeDetected\fP
- event types. The \fBevents\fP parameter is not used.
- .SH STATISTICS ENDPOINTS
- .SS GET /rest/stats/device
- .sp
- Returns general statistics about devices. Currently, only contains the
- time the device was last seen and the last connection duration.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-s http://localhost:8384/rest/stats/device | json
- {
- \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq: {
- \(dqlastSeen\(dq : \(dq2015\-04\-18T11:21:31.3256277+01:00\(dq
- \(dqlastConnectionDurationS\(dq: 556335.421708141
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/stats/folder
- .sp
- Returns general statistics about folders. Currently contains the
- last scan time and the last synced file.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqfolderid\(dq: {
- \(dqlastScan\(dq: \(dq2016\-06\-02T13:28:01.288181412\-04:00\(dq,
- \(dqlastFile\(dq: {
- \(dqfilename\(dq: \(dqfile/name\(dq,
- \(dqat\(dq: \(dq2015\-04\-16T22:04:18.3066971+01:00\(dq
- }
- }
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SH MISC SERVICES ENDPOINTS
- .SS GET /rest/svc/deviceid
- .sp
- Verifies and formats a device ID. Accepts all currently valid formats
- (52 or 56 characters with or without separators, upper or lower case,
- with trivial substitutions). Takes one parameter, \fBid\fP, and returns
- either a valid device ID in modern format, or an error.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-s http://localhost:8384/rest/svc/deviceid?id=1234 | json
- {
- \(dqerror\(dq: \(dqdevice ID invalid: incorrect length\(dq
- }
- $ curl \-s http://localhost:8384/rest/svc/deviceid?id=p56ioi7m\-\-zjnu2iq\-gdr\-eydm\-2mgtmgl3bxnpq6w5btbbz4tjxzwicq | json
- {
- \(dqid\(dq: \(dqP56IOI7\-MZJNU2Y\-IQGDREY\-DM2MGTI\-MGL3BXN\-PQ6W5BM\-TBBZ4TJ\-XZWICQ2\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/svc/lang
- .sp
- Returns a list of canonicalized localization codes, as picked up from
- the \fBAccept\-Language\fP header sent by the browser.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- [\(dqsv_sv\(dq,\(dqsv\(dq,\(dqen_us\(dq,\(dqen\(dq]
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/svc/random/string
- .sp
- Returns a strong random generated string (alphanumeric) of the specified length. Takes the \fBlength\fP parameter.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqrandom\(dq: \(dqFdPaEaZQ56sXEKYNxpgF\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SS GET /rest/svc/report
- .sp
- Returns the data sent in the anonymous usage report.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqfolderMaxMiB\(dq : 0,
- \(dqplatform\(dq : \(dqlinux\-amd64\(dq,
- \(dqtotMiB\(dq : 0,
- \(dqlongVersion\(dq : \(dqsyncthing v0.12.2 \e\(dqBeryllium Bedbug\e\(dq (go1.4.3 linux\-amd64 default) unknown\-user@build2.syncthing.net 2015\-11\-09 13:23:26 UTC\(dq,
- \(dqupgradeAllowedManual\(dq : true,
- \(dqtotFiles\(dq : 3,
- \(dqfolderUses\(dq : {
- \(dqignorePerms\(dq : 0,
- \(dqautoNormalize\(dq : 0,
- \(dqsendonly\(dq : 0,
- \(dqignoreDelete\(dq : 0
- },
- \(dqmemoryUsageMiB\(dq : 13,
- \(dqversion\(dq : \(dqv0.12.2\(dq,
- \(dqsha256Perf\(dq : 27.28,
- \(dqnumFolders\(dq : 2,
- \(dqmemorySize\(dq : 1992,
- \(dqannounce\(dq : {
- \(dqdefaultServersIP\(dq : 0,
- \(dqotherServers\(dq : 0,
- \(dqglobalEnabled\(dq : false,
- \(dqdefaultServersDNS\(dq : 1,
- \(dqlocalEnabled\(dq : false
- },
- \(dqusesRateLimit\(dq : false,
- \(dqnumCPU\(dq : 2,
- \(dquniqueID\(dq : \(dq\(dq,
- \(dqurVersion\(dq : 2,
- \(dqrescanIntvs\(dq : [
- 60,
- 60
- ],
- \(dqnumDevices\(dq : 2,
- \(dqfolderMaxFiles\(dq : 3,
- \(dqrelays\(dq : {
- \(dqdefaultServers\(dq : 1,
- \(dqenabled\(dq : true,
- \(dqotherServers\(dq : 0
- },
- \(dqdeviceUses\(dq : {
- \(dqcompressMetadata\(dq : 1,
- \(dqcustomCertName\(dq : 0,
- \(dqstaticAddr\(dq : 1,
- \(dqcompressAlways\(dq : 0,
- \(dqcompressNever\(dq : 1,
- \(dqintroducer\(dq : 0,
- \(dqdynamicAddr\(dq : 1
- },
- \(dqupgradeAllowedAuto\(dq : false
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SH DEBUG ENDPOINTS
- .SS Debug Endpoints
- .sp
- These endpoints require the \fI\%gui.debugging\fP configuration option to
- be enabled and yield an access denied error code otherwise.
- .SS GET /rest/debug/peerCompletion
- .sp
- Summarizes the completion percentage for each remote device. Returns an object
- with device IDs as keys and an integer percentage as values.
- .SS GET /rest/debug/httpmetrics
- .sp
- Returns statistics about each served REST API endpoint, to diagnose how much
- time was spent generating the responses.
- .SS GET /rest/debug/cpuprof
- .sp
- Used to capture a profile of what Syncthing is doing on the CPU. See
- \fI\%Profiling\fP\&.
- .SS GET /rest/debug/heapprof
- .sp
- Used to capture a profile of what Syncthing is doing with the heap memory. See
- \fI\%Profiling\fP\&.
- .SS GET /rest/debug/support
- .sp
- Collects information about the running instance for troubleshooting purposes.
- Returns a “support bundle” as a zipped archive, which should be sent to the
- developers after verifying it contains no sensitive personal information.
- Credentials for the web GUI and the API key are automatically redacted already.
- .SS GET /rest/debug/file
- .sp
- Shows diagnostics about a certain file in a shared folder. Takes the \fBfolder\fP
- (folder ID) and \fBfile\fP (folder relative path) parameters.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- $ curl \-H X\-API\-Key:... \(dqhttp://localhost:8384/rest/debug/file?folder=default&file=foo/bar\(dq
- .EE
- .UNINDENT
- .UNINDENT
- .sp
- The returned object contains the same info as \fI\%GET /rest/db/file\fP, plus a summary
- of \fBglobalVersions\fP\&.
- .SH NOAUTH ENDPOINTS
- .sp
- Calls that do not require authentication.
- .SS GET /rest/noauth/health
- .sp
- Returns a \fB{\(dqstatus\(dq: \(dqOK\(dq}\fP object.
- .INDENT 0.0
- .INDENT 3.5
- .sp
- .EX
- {
- \(dqstatus\(dq: \(dqOK\(dq
- }
- .EE
- .UNINDENT
- .UNINDENT
- .SH AUTHOR
- The Syncthing Authors
- .SH COPYRIGHT
- 2014-2019, The Syncthing Authors
- .\" Generated by docutils manpage writer.
- .
|