-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathapi.html
More file actions
212 lines (210 loc) · 100 KB
/
api.html
File metadata and controls
212 lines (210 loc) · 100 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>API | Foldergram</title>
<meta name="description" content="Backend endpoints, parameters, response shapes, and mutation rules in Foldergram.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.D0ri7LhZ.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.Ctsaibyu.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.DJE1TC2M.js">
<link rel="modulepreload" href="/assets/chunks/framework.ePeAWSvT.js">
<link rel="modulepreload" href="/assets/api.md.Dq0npsCa.lean.js">
<link rel="icon" type="image/svg+xml" href="/logo.svg">
<link rel="apple-touch-icon" href="/logo.svg">
<meta name="theme-color" content="#6366f1">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-b831c05f><!--[--><!--]--><!--[--><span tabindex="-1" data-v-9178e81a></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-9178e81a>Skip to content</a><!--]--><!----><header class="VPNav" data-v-b831c05f data-v-2222ab16><div class="VPNavBar" data-v-2222ab16 data-v-3a1adb31><div class="wrapper" data-v-3a1adb31><div class="container" data-v-3a1adb31><div class="title" data-v-3a1adb31><div class="VPNavBarTitle has-sidebar" data-v-3a1adb31 data-v-7c1b0e18><a class="title" href="/" data-v-7c1b0e18><!--[--><!--]--><!--[--><img class="VPImage logo" src="/logo.svg" alt data-v-84be65fe><!--]--><span data-v-7c1b0e18>Foldergram</span><!--[--><!--]--></a></div></div><div class="content" data-v-3a1adb31><div class="content-body" data-v-3a1adb31><!--[--><!--]--><div class="VPNavBarSearch search" data-v-3a1adb31><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-3a1adb31 data-v-b187e594><span id="main-nav-aria-label" class="visually-hidden" data-v-b187e594> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/quick-start" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>Quick Start</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/installation" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>Installation</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/configuration" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>Configuration</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/how-it-works" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>How It Works</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink active" href="/api" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>API</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/security" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>Security</span><!--]--></a><!--]--><!--[--><a class="VPLink link vp-external-link-icon VPNavBarMenuLink" href="https://foldergram.intentdeep.com/" target="_blank" rel="noreferrer" tabindex="0" data-v-b187e594 data-v-4599aa41><!--[--><span data-v-4599aa41>Demo</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-3a1adb31 data-v-df187b99><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-df187b99 data-v-8e7bc7a0 data-v-dc0f6ec6><span class="check" data-v-dc0f6ec6><span class="icon" data-v-dc0f6ec6><!--[--><span class="vpi-sun sun" data-v-8e7bc7a0></span><span class="vpi-moon moon" data-v-8e7bc7a0></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-3a1adb31 data-v-ed584c66 data-v-2b546b40><!--[--><a class="VPSocialLink no-icon" href="https://github.com/foldergram/foldergram" aria-label="github" target="_blank" rel="noopener" data-v-2b546b40 data-v-9ca19b6a><span class="vpi-social-github"></span></a><!--]--></div><div class="VPFlyout VPNavBarExtra extra" data-v-3a1adb31 data-v-7fd1485d data-v-5d90fd5a><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-5d90fd5a><span class="vpi-more-horizontal icon" data-v-5d90fd5a></span></button><div class="menu" data-v-5d90fd5a><div class="VPMenu" data-v-5d90fd5a data-v-565e72ed><!----><!--[--><!--[--><!----><div class="group" data-v-7fd1485d><div class="item appearance" data-v-7fd1485d><p class="label" data-v-7fd1485d>Appearance</p><div class="appearance-action" data-v-7fd1485d><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-7fd1485d data-v-8e7bc7a0 data-v-dc0f6ec6><span class="check" data-v-dc0f6ec6><span class="icon" data-v-dc0f6ec6><!--[--><span class="vpi-sun sun" data-v-8e7bc7a0></span><span class="vpi-moon moon" data-v-8e7bc7a0></span><!--]--></span></span></button></div></div></div><div class="group" data-v-7fd1485d><div class="item social-links" data-v-7fd1485d><div class="VPSocialLinks social-links-list" data-v-7fd1485d data-v-2b546b40><!--[--><a class="VPSocialLink no-icon" href="https://github.com/foldergram/foldergram" aria-label="github" target="_blank" rel="noopener" data-v-2b546b40 data-v-9ca19b6a><span class="vpi-social-github"></span></a><!--]--></div></div></div><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-3a1adb31 data-v-7b1e48c5><span class="container" data-v-7b1e48c5><span class="top" data-v-7b1e48c5></span><span class="middle" data-v-7b1e48c5></span><span class="bottom" data-v-7b1e48c5></span></span></button></div></div></div></div><div class="divider" data-v-3a1adb31><div class="divider-line" data-v-3a1adb31></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-b831c05f data-v-a3b82d7b><div class="container" data-v-a3b82d7b><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-a3b82d7b><span class="vpi-align-left menu-icon" data-v-a3b82d7b></span><span class="menu-text" data-v-a3b82d7b>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-a3b82d7b data-v-84597ab5><button data-v-84597ab5>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-b831c05f data-v-e0bd508c><div class="curtain" data-v-e0bd508c></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-e0bd508c><span class="visually-hidden" id="sidebar-aria-label" data-v-e0bd508c> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-aef8ce5e><section class="VPSidebarItem level-0" data-v-aef8ce5e data-v-44dbf5ab><div class="item" role="button" tabindex="0" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><h2 class="text" data-v-44dbf5ab>Guide</h2><!----></div><div class="items" data-v-44dbf5ab><!--[--><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/quick-start" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Quick Start</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/installation" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Installation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/configuration" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Configuration</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-aef8ce5e><section class="VPSidebarItem level-0" data-v-aef8ce5e data-v-44dbf5ab><div class="item" role="button" tabindex="0" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><h2 class="text" data-v-44dbf5ab>Product</h2><!----></div><div class="items" data-v-44dbf5ab><!--[--><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/how-it-works" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>How It Works</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/features" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Features</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/media-processing" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Media Processing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/security" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Security</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-aef8ce5e><section class="VPSidebarItem level-0 has-active" data-v-aef8ce5e data-v-44dbf5ab><div class="item" role="button" tabindex="0" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><h2 class="text" data-v-44dbf5ab>Reference</h2><!----></div><div class="items" data-v-44dbf5ab><!--[--><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/api" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>API</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/development" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Development</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/troubleshooting" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>Troubleshooting</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-44dbf5ab data-v-44dbf5ab><div class="item" data-v-44dbf5ab><div class="indicator" data-v-44dbf5ab></div><a class="VPLink link link" href="/faq" data-v-44dbf5ab><!--[--><p class="text" data-v-44dbf5ab>FAQ</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-b831c05f data-v-bf3f1372><div class="VPDoc has-sidebar has-aside" data-v-bf3f1372 data-v-7c2da6bf><!--[--><!--]--><div class="container" data-v-7c2da6bf><div class="aside" data-v-7c2da6bf><div class="aside-curtain" data-v-7c2da6bf></div><div class="aside-container" data-v-7c2da6bf><div class="aside-content" data-v-7c2da6bf><div class="VPDocAside" data-v-7c2da6bf data-v-c3c6bcbc><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-c3c6bcbc data-v-16b74dc6><div class="content" data-v-16b74dc6><div class="outline-marker" data-v-16b74dc6></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-16b74dc6>On this page</div><ul class="VPDocOutlineItem root" data-v-16b74dc6 data-v-8c1c05d6><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-c3c6bcbc></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-7c2da6bf><div class="content-container" data-v-7c2da6bf><!--[--><!--]--><main class="main" data-v-7c2da6bf><div style="position:relative;" class="vp-doc _api" data-v-7c2da6bf><div><h1 id="api" tabindex="-1">API <a class="header-anchor" href="#api" aria-label="Permalink to "API""></a></h1><p>All documented routes come from <code>server/src/routes/api.ts</code>.</p><h2 id="base-paths" tabindex="-1">Base paths <a class="header-anchor" href="#base-paths" aria-label="Permalink to "Base paths""></a></h2><table tabindex="0"><thead><tr><th>Base path</th><th>Purpose</th></tr></thead><tbody><tr><td><code>/api</code></td><td>JSON API</td></tr><tr><td><code>/thumbnails</code></td><td>Protected thumbnail derivatives, served from cache or generated on demand in lazy mode</td></tr><tr><td><code>/previews</code></td><td>Protected preview derivatives, served from cache or generated on demand in lazy mode</td></tr></tbody></table><h2 id="authentication-and-protected-routes" tabindex="-1">Authentication and protected routes <a class="header-anchor" href="#authentication-and-protected-routes" aria-label="Permalink to "Authentication and protected routes""></a></h2><p>Foldergram can optionally require a role-bearing password session.</p><p>When password protection is enabled:</p><ul><li>most <code>/api</code> routes return <code>401</code> until the browser logs in, except for safe read routes in public viewer mode</li><li><code>GET /api/health</code>, <code>GET /api/auth/status</code>, <code>POST /api/auth/login</code>, <code>POST /api/auth/unlock-admin</code>, and <code>POST /api/auth/logout</code> stay reachable without an authenticated session</li><li><code>PUT /api/auth/password</code> is public only when password protection is currently disabled, so the first admin password can be set</li><li><code>/thumbnails/...</code> and <code>/previews/...</code> also require the same authenticated session unless public viewer mode is enabled</li><li>authenticated sessions carry <code>admin</code> or <code>viewer</code> role data</li><li>anonymous public reads use <code>role: "anonymous"</code> and <code>likesMode: "local"</code></li><li>admin-only mutations return <code>403</code> for viewer sessions</li></ul><p>The frontend sends same-origin credentials automatically and uses a signed cookie-based session.</p><h2 id="mutation-requirements" tabindex="-1">Mutation requirements <a class="header-anchor" href="#mutation-requirements" aria-label="Permalink to "Mutation requirements""></a></h2><p>All mutating API routes are protected by <code>requireTrustedMutationRequest</code>.</p><h3 id="required-header" tabindex="-1">Required header <a class="header-anchor" href="#required-header" aria-label="Permalink to "Required header""></a></h3><div class="language-http vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">http</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">x-foldergram-intent</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 1</span></span></code></pre></div><h3 id="local-origin-checks" tabindex="-1">Local-origin checks <a class="header-anchor" href="#local-origin-checks" aria-label="Permalink to "Local-origin checks""></a></h3><p>For mutating requests:</p><ul><li>if <code>Origin</code> is present, it must be <code>localhost</code>, <code>127.0.0.1</code>, or <code>::1</code></li><li>in development and test, the origin port must match <code>DEV_SERVER_PORT</code> or the reserved dev-client range from <code>DEV_CLIENT_PORT</code> through <code>DEV_CLIENT_PORT + 3</code></li><li>in production, loopback origins are allowed and same-host origins are allowed when they match the host serving the app on <code>SERVER_PORT</code></li><li>if <code>Origin</code> is absent but <code>Referer</code> is present, the same loopback check is applied to the referer origin</li></ul><p>The shipped frontend adds <code>x-foldergram-intent: 1</code> automatically for <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, and <code>DELETE</code> requests.</p><h2 id="common-error-behavior" tabindex="-1">Common error behavior <a class="header-anchor" href="#common-error-behavior" aria-label="Permalink to "Common error behavior""></a></h2><table tabindex="0"><thead><tr><th>Status</th><th>When it happens</th></tr></thead><tbody><tr><td><code>401</code></td><td>Password protection is enabled and the request is not authenticated.</td></tr><tr><td><code>400</code></td><td>Validation or request-shape errors surfaced through the Express error handler.</td></tr><tr><td><code>403</code></td><td>Missing intent header, failed local-origin check, or a viewer session hitting an admin-only route.</td></tr><tr><td><code>404</code></td><td>Missing folder, post, moment, or original media.</td></tr><tr><td><code>409</code></td><td>A scan or thumbnail rebuild was requested while the library requires a library-index rebuild after a gallery-root change.</td></tr></tbody></table><h2 id="read-endpoints" tabindex="-1">Read endpoints <a class="header-anchor" href="#read-endpoints" aria-label="Permalink to "Read endpoints""></a></h2><h3 id="get-api-health" tabindex="-1"><code>GET /api/health</code> <a class="header-anchor" href="#get-api-health" aria-label="Permalink to "`GET /api/health`""></a></h3><p>Returns process-level health plus storage state.</p><p>Example shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "timestamp"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"2026-03-16T12:34:56.000Z"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "storage"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "available"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "reason"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "usingInMemoryDatabase"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="get-api-auth-status" tabindex="-1"><code>GET /api/auth/status</code> <a class="header-anchor" href="#get-api-auth-status" aria-label="Permalink to "`GET /api/auth/status`""></a></h3><p>Returns the current auth state for the browser session.</p><p>Example shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "enabled"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "authenticated"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"anonymous"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "accessMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"public"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "likesMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"local"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "capabilities"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canManageLibrary"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canDeleteMedia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canAccessSettings"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseSharedLikes"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseLocalFavorites"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="get-api-feed" tabindex="-1"><code>GET /api/feed</code> <a class="header-anchor" href="#get-api-feed" aria-label="Permalink to "`GET /api/feed`""></a></h3><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td><code>1</code></td><td>Minimum <code>1</code>.</td></tr><tr><td><code>limit</code></td><td>integer</td><td><code>24</code></td><td>Minimum <code>1</code>, maximum <code>60</code>.</td></tr><tr><td><code>mode</code></td><td>`recent</td><td>rediscover</td><td>random`</td></tr><tr><td><code>seed</code></td><td>integer</td><td>unset</td><td>Optional random seed for <code>random</code> mode.</td></tr></tbody></table><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "mode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recent"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "page"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "limit"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">24</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "total"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasMore"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li><code>items</code> contain both images and videos.</li><li><code>thumbnailUrl</code> points to <code>/thumbnails/...</code>.</li><li><code>previewUrl</code> points to <code>/previews/...</code>.</li></ul><h3 id="get-api-reels" tabindex="-1"><code>GET /api/reels</code> <a class="header-anchor" href="#get-api-reels" aria-label="Permalink to "`GET /api/reels`""></a></h3><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td><code>1</code></td><td>Minimum <code>1</code>.</td></tr><tr><td><code>limit</code></td><td>integer</td><td><code>24</code></td><td>Minimum <code>1</code>, maximum <code>60</code>. The current client helper requests <code>6</code> per page.</td></tr><tr><td><code>mode</code></td><td>`recommended</td><td>recent</td><td>random`</td></tr><tr><td><code>seed</code></td><td>integer</td><td>unset</td><td>Optional seed used to keep <code>recommended</code> and <code>random</code> queues stable while paging.</td></tr><tr><td><code>lastFolder</code></td><td>string</td><td>unset</td><td>Optional recent-navigation hint used by <code>recommended</code>.</td></tr><tr><td><code>recentFolders</code></td><td>comma-separated string</td><td>unset</td><td>Optional recent-navigation hints used by <code>recommended</code>.</td></tr></tbody></table><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "mode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recommended"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "page"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "limit"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">6</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "total"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasMore"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li><code>items</code> contain videos only.</li><li><code>recommended</code> uses <code>lastFolder</code> and <code>recentFolders</code> to bias the queue toward folders you recently opened.</li><li><code>recent</code> ignores recommendation hints and returns newest indexed videos first.</li><li><code>random</code> and <code>recommended</code> stay stable across pages when the same <code>seed</code> is reused.</li></ul><h3 id="get-api-feed-moments" tabindex="-1"><code>GET /api/feed/moments</code> <a class="header-anchor" href="#get-api-feed-moments" aria-label="Permalink to "`GET /api/feed/moments`""></a></h3><p>Returns the current Home Moments or Highlights definition.</p><p>The response can be:</p><ul><li><code>moments</code></li><li><code>highlights</code></li></ul><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railKind"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"moments"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railTitle"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Moments"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railDescription"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Memory capsules shaped by real capture dates from your library."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railSingularLabel"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Moment"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="get-api-feed-moments-id" tabindex="-1"><code>GET /api/feed/moments/:id</code> <a class="header-anchor" href="#get-api-feed-moments-id" aria-label="Permalink to "`GET /api/feed/moments/:id`""></a></h3><p>Path parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td></tr></tbody></table><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td><code>1</code></td></tr><tr><td><code>limit</code></td><td>integer</td><td><code>24</code></td></tr></tbody></table><p>Returns <code>404</code> with <code>{"message":"Feed capsule not found"}</code> when the ID does not exist in the currently selected set.</p><h3 id="get-api-folders" tabindex="-1"><code>GET /api/folders</code> <a class="header-anchor" href="#get-api-folders" aria-label="Permalink to "`GET /api/folders`""></a></h3><p>Returns:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Each item is a folder summary with:</p><ul><li><code>id</code></li><li><code>slug</code></li><li><code>name</code></li><li><code>description</code></li><li><code>folderPath</code></li><li><code>breadcrumb</code></li><li><code>imageCount</code></li><li><code>videoCount</code></li><li><code>latestImageMtimeMs</code></li><li><code>hasAvatarStory</code></li><li><code>avatarImageId</code></li><li><code>avatarUrl</code></li></ul><h3 id="get-api-folders-slug" tabindex="-1"><code>GET /api/folders/:slug</code> <a class="header-anchor" href="#get-api-folders-slug" aria-label="Permalink to "`GET /api/folders/:slug`""></a></h3><p>Returns one folder summary.</p><p>The response uses the same shape as folder items from <code>GET /api/folders</code>, including <code>hasAvatarStory</code> so the client can decide whether the folder avatar should open a story entry point.</p><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Folder not found"}</code> if the slug is missing</li></ul><h3 id="get-api-folders-slug-images" tabindex="-1"><code>GET /api/folders/:slug/images</code> <a class="header-anchor" href="#get-api-folders-slug-images" aria-label="Permalink to "`GET /api/folders/:slug/images`""></a></h3><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td><code>1</code></td><td>Minimum <code>1</code>.</td></tr><tr><td><code>limit</code></td><td>integer</td><td><code>24</code></td><td>Minimum <code>1</code>, maximum <code>60</code>.</td></tr><tr><td><code>mediaType</code></td><td>`image</td><td>video`</td><td>unset</td></tr></tbody></table><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "folder"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "slug"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"oslo"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"oslo"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "description"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "folderPath"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"trips/oslo"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "breadcrumb"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"trips"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "imageCount"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">12</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "videoCount"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "latestImageMtimeMs"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1700000000000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasAvatarStory"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "avatarImageId"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "avatarUrl"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"/thumbnails/trips/oslo/IMG_0001.webp?v=4"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "page"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "limit"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">24</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "total"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">12</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasMore"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Folder not found"}</code></li></ul><h3 id="get-api-folders-slug-stories" tabindex="-1"><code>GET /api/folders/:slug/stories</code> <a class="header-anchor" href="#get-api-folders-slug-stories" aria-label="Permalink to "`GET /api/folders/:slug/stories`""></a></h3><p>Returns the stories payload for one folder.</p><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railKind"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railTitle"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railDescription"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Stories and highlights for AnimalPlanet."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railSingularLabel"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Story"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasAvatarStory"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "avatarStoryId"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"animalplanet-stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "highlights"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li><code>items</code> contains the avatar story first when one exists, followed by highlight capsules.</li><li><code>highlights</code> contains only highlight capsules.</li><li>each capsule item includes <code>id</code>, <code>title</code>, <code>subtitle</code>, <code>dateContext</code>, <code>imageCount</code>, <code>coverImage</code>, and <code>presentation</code></li><li><code>presentation</code> is <code>avatar</code> or <code>highlight</code></li><li><code>avatarStoryId</code> can be a synthetic fallback id when the folder has highlight media but no direct avatar-story files</li></ul><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Folder not found"}</code></li></ul><h3 id="get-api-folders-slug-stories-id" tabindex="-1"><code>GET /api/folders/:slug/stories/:id</code> <a class="header-anchor" href="#get-api-folders-slug-stories-id" aria-label="Permalink to "`GET /api/folders/:slug/stories/:id`""></a></h3><p>Path parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th></tr></thead><tbody><tr><td><code>slug</code></td><td>string</td></tr><tr><td><code>id</code></td><td>string</td></tr></tbody></table><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td><code>1</code></td></tr><tr><td><code>limit</code></td><td>integer</td><td><code>24</code></td></tr></tbody></table><p>Response shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railKind"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railTitle"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railDescription"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Stories and highlights for AnimalPlanet."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "railSingularLabel"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Story"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "story"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"animalplanet-stories"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "title"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"AnimalPlanet"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "subtitle"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"AnimalPlanet story set"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "dateContext"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Today"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "imageCount"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "presentation"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"avatar"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "coverImage"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {}</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "page"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "limit"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">24</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "total"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "hasMore"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li>the paginated <code>items</code> array contains normal feed-item payloads</li><li>if the requested avatar story is a fallback capsule, the server returns recent highlight media for that synthetic capsule</li></ul><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Story capsule not found"}</code></li></ul><h3 id="get-api-likes" tabindex="-1"><code>GET /api/likes</code> <a class="header-anchor" href="#get-api-likes" aria-label="Permalink to "`GET /api/likes`""></a></h3><p>Returns:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Items are ordered by like timestamp descending.</p><p>Notes:</p><ul><li>shared likes are available to <code>admin</code> and <code>viewer</code> sessions</li><li>anonymous public sessions use browser-local favorites instead of this endpoint</li></ul><h3 id="get-api-images-id" tabindex="-1"><code>GET /api/images/:id</code> <a class="header-anchor" href="#get-api-images-id" aria-label="Permalink to "`GET /api/images/:id`""></a></h3><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>mediaType</code></td><td>`image</td><td>video`</td></tr></tbody></table><p>Returns one post detail payload with:</p><ul><li>feed-item fields</li><li><code>relativePath</code></li><li><code>mimeType</code></li><li><code>fileSize</code></li><li><code>originalUrl</code></li><li><code>playbackStrategy</code> for videos when an original MP4 is browser-compatible</li><li><code>nextImageId</code></li><li><code>previousImageId</code></li></ul><p><code>nextImageId</code> and <code>previousImageId</code> are resolved within the same folder and the same active <code>mediaType</code> filter when one is supplied.</p><p>Detail media rules:</p><ul><li>if <code>IMAGE_DETAIL_SOURCE=original</code> and the item is an image, <code>previewUrl</code> points to <code>/api/originals/:id</code></li><li>videos keep <code>previewUrl</code> on <code>/previews/...</code></li><li>compatible original MP4 videos can set <code>playbackStrategy: "original"</code> so the client can expose an optional original-quality switch</li></ul><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Post not found"}</code></li></ul><h3 id="get-api-originals-id" tabindex="-1"><code>GET /api/originals/:id</code> <a class="header-anchor" href="#get-api-originals-id" aria-label="Permalink to "`GET /api/originals/:id`""></a></h3><p>Serves the original file from disk by image ID only.</p><p>Rules:</p><ul><li>the indexed path must still exist</li><li>the resolved path must stay within <code>GALLERY_ROOT</code></li><li>deleted posts do not resolve</li></ul><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Original media not found"}</code></li></ul><h3 id="get-api-status" tabindex="-1"><code>GET /api/status</code> <a class="header-anchor" href="#get-api-status" aria-label="Permalink to "`GET /api/status`""></a></h3><p>Returns viewer-safe operational state for the shell.</p><p>When access protection is enabled:</p><ul><li><code>admin</code> and <code>viewer</code> sessions can always read it</li><li>anonymous visitors can also read it when <code>viewer_access_mode=public</code></li></ul><p>Notable fields:</p><table tabindex="0"><thead><tr><th>Field</th><th>Notes</th></tr></thead><tbody><tr><td><code>folders</code></td><td>Active indexed folders.</td></tr><tr><td><code>indexedImages</code></td><td>Active indexed posts. The name is historical and still includes videos in the total feed count.</td></tr><tr><td><code>indexedVideos</code></td><td>Active indexed videos only.</td></tr><tr><td><code>scan</code></td><td>Live scan progress snapshot. <code>currentFolder</code> is redacted and <code>lastCompletedScan.error_text</code> is always <code>null</code>.</td></tr><tr><td><code>storage</code></td><td>Availability with a generic unavailable message only.</td></tr><tr><td><code>libraryIndex</code></td><td>Rebuild requirement plus ignored root-media count. Gallery-root paths are omitted.</td></tr><tr><td><code>preferences.defaultHomeFeedMode</code></td><td>Current app-wide default home feed mode.</td></tr><tr><td><code>preferences.defaultReelsFeedMode</code></td><td>Current app-wide default reels mode used when <code>/reels</code> opens.</td></tr><tr><td><code>preferences.treatStoriesAsFolders</code></td><td>Whether folders literally named <code>stories</code> are treated as ordinary app folders instead of reserved story sources.</td></tr><tr><td><code>storiesMigration</code></td><td>Migration hint with <code>hasLegacyStoriesCandidates</code> and <code>decisionPending</code>.</td></tr></tbody></table><h3 id="get-api-admin-stats" tabindex="-1"><code>GET /api/admin/stats</code> <a class="header-anchor" href="#get-api-admin-stats" aria-label="Permalink to "`GET /api/admin/stats`""></a></h3><p>Returns the full admin operational payload.</p><p>This route is read-only but <code>admin</code>-only. It extends <code>GET /api/status</code> with the additional fields below:</p><table tabindex="0"><thead><tr><th>Field</th><th>Notes</th></tr></thead><tbody><tr><td><code>deletedImages</code></td><td>Soft-deleted post count.</td></tr><tr><td><code>thumbnailCount</code></td><td>Actual generated thumbnail files currently present on disk.</td></tr><tr><td><code>previewCount</code></td><td>Actual generated preview files currently present on disk.</td></tr><tr><td><code>storage.usingInMemoryDatabase</code></td><td>Whether SQLite had to fall back to in-memory mode.</td></tr><tr><td><code>libraryIndex.currentGalleryRoot</code></td><td>Current configured gallery root.</td></tr><tr><td><code>libraryIndex.previousGalleryRoot</code></td><td>Prior configured gallery root when the root changed.</td></tr><tr><td><code>libraryIndex.lastSuccessfulGalleryRoot</code></td><td>Gallery root from the last completed successful scan.</td></tr><tr><td><code>lastScan</code></td><td>Last completed scan run.</td></tr></tbody></table><p>The same <code>preferences.treatStoriesAsFolders</code> and <code>storiesMigration</code> fields from <code>GET /api/status</code> are also present here.</p><h2 id="mutating-endpoints" tabindex="-1">Mutating endpoints <a class="header-anchor" href="#mutating-endpoints" aria-label="Permalink to "Mutating endpoints""></a></h2><h3 id="post-api-auth-login" tabindex="-1"><code>POST /api/auth/login</code> <a class="header-anchor" href="#post-api-auth-login" aria-label="Permalink to "`POST /api/auth/login`""></a></h3><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"your-admin-or-viewer-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "auth"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "enabled"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "authenticated"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"viewer"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "accessMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "likesMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"shared"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "capabilities"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canManageLibrary"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canDeleteMedia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canAccessSettings"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseSharedLikes"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseLocalFavorites"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>400</code> if password protection is not enabled</li><li><code>401</code> if the password is incorrect</li><li><code>403</code> when trust requirements are missing</li></ul><h3 id="post-api-auth-unlock-admin" tabindex="-1"><code>POST /api/auth/unlock-admin</code> <a class="header-anchor" href="#post-api-auth-unlock-admin" aria-label="Permalink to "`POST /api/auth/unlock-admin`""></a></h3><p>Elevates the current browser into an admin session by verifying the admin password.</p><p>This route stays reachable without an existing authenticated session so it can be used from viewer mode and public mode.</p><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"your-admin-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "auth"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "enabled"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "authenticated"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"admin"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "accessMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"public"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "likesMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"shared"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "capabilities"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canManageLibrary"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canDeleteMedia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canAccessSettings"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseSharedLikes"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "canUseLocalFavorites"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>400</code> if password protection is not enabled</li><li><code>401</code> if the admin password is incorrect</li><li><code>403</code> when trust requirements are missing</li></ul><h3 id="post-api-auth-logout" tabindex="-1"><code>POST /api/auth/logout</code> <a class="header-anchor" href="#post-api-auth-logout" aria-label="Permalink to "`POST /api/auth/logout`""></a></h3><p>Clears the current browser session cookie.</p><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "auth"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "enabled"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "authenticated"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="put-api-auth-password" tabindex="-1"><code>PUT /api/auth/password</code> <a class="header-anchor" href="#put-api-auth-password" aria-label="Permalink to "`PUT /api/auth/password`""></a></h3><p>Sets or changes the admin password.</p><p>Body when protection is disabled:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"new-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Body when protection is already enabled:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "currentPassword"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"old-password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"new-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li>password minimum length is <code>8</code></li><li><code>viewer</code> sessions receive <code>403</code></li><li>changing the password invalidates older sessions</li></ul><h3 id="delete-api-auth-password" tabindex="-1"><code>DELETE /api/auth/password</code> <a class="header-anchor" href="#delete-api-auth-password" aria-label="Permalink to "`DELETE /api/auth/password`""></a></h3><p>Disables password protection entirely.</p><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "currentPassword"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"current-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>400</code> if protection is already disabled</li><li><code>401</code> if the password is incorrect</li><li><code>403</code> if the current session is not <code>admin</code></li></ul><h3 id="put-api-auth-viewer-access" tabindex="-1"><code>PUT /api/auth/viewer-access</code> <a class="header-anchor" href="#put-api-auth-viewer-access" aria-label="Permalink to "`PUT /api/auth/viewer-access`""></a></h3><p>Configures viewer access mode.</p><p>Body for admin-only access:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "mode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"off"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Body for password-protected viewer access:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "mode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"password"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "viewerPassword"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"viewer-password"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li><code>viewerPassword</code> is required when <code>mode=password</code></li><li>viewer and admin passwords must differ</li><li>changing viewer access invalidates older sessions</li><li><code>mode=public</code> enables anonymous browsing immediately</li><li>anonymous public sessions use local browser favorites instead of shared <code>/api/likes</code></li></ul><h3 id="put-api-admin-settings-home-feed-default" tabindex="-1"><code>PUT /api/admin/settings/home-feed-default</code> <a class="header-anchor" href="#put-api-admin-settings-home-feed-default" aria-label="Permalink to "`PUT /api/admin/settings/home-feed-default`""></a></h3><p>Sets the default mode used when Home opens.</p><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "defaultMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recent"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Allowed values:</p><ul><li><code>recent</code></li><li><code>rediscover</code></li><li><code>random</code></li></ul><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "defaultMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recent"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="put-api-admin-settings-reels-feed-default" tabindex="-1"><code>PUT /api/admin/settings/reels-feed-default</code> <a class="header-anchor" href="#put-api-admin-settings-reels-feed-default" aria-label="Permalink to "`PUT /api/admin/settings/reels-feed-default`""></a></h3><p>Sets the app-wide default mode used when <code>/reels</code> opens.</p><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "defaultMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recommended"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Allowed values:</p><ul><li><code>recommended</code></li><li><code>recent</code></li><li><code>random</code></li></ul><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "defaultMode"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"recommended"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="put-api-admin-settings-stories-mode" tabindex="-1"><code>PUT /api/admin/settings/stories-mode</code> <a class="header-anchor" href="#put-api-admin-settings-stories-mode" aria-label="Permalink to "`PUT /api/admin/settings/stories-mode`""></a></h3><p>Sets how folders literally named <code>stories</code> are interpreted.</p><p>Body:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "treatStoriesAsFolders"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "treatStoriesAsFolders"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Notes:</p><ul><li><code>false</code> enables the default reserved-stories mode</li><li><code>true</code> keeps <code>stories/</code> folders behaving like ordinary app folders</li><li>the Settings UI immediately follows this write with <code>POST /api/admin/rescan</code>, but this endpoint itself only saves the setting</li></ul><h3 id="post-api-images-id-like" tabindex="-1"><code>POST /api/images/:id/like</code> <a class="header-anchor" href="#post-api-images-id-like" aria-label="Permalink to "`POST /api/images/:id/like`""></a></h3><p>Marks a post as liked.</p><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "liked"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Image not found"}</code> when the post does not exist or is deleted</li><li><code>403</code> when trust requirements are missing</li></ul><h3 id="delete-api-images-id-like" tabindex="-1"><code>DELETE /api/images/:id/like</code> <a class="header-anchor" href="#delete-api-images-id-like" aria-label="Permalink to "`DELETE /api/images/:id/like`""></a></h3><p>Removes a like.</p><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "liked"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="delete-api-images-id" tabindex="-1"><code>DELETE /api/images/:id</code> <a class="header-anchor" href="#delete-api-images-id" aria-label="Permalink to "`DELETE /api/images/:id`""></a></h3><p>Permanently deletes:</p><ul><li>the source file from disk</li><li>its thumbnail derivative</li><li>its preview derivative</li></ul><p>Then it updates the index and folder avatar state.</p><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "folderSlug"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"oslo"</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Image not found"}</code></li><li><code>403</code> for viewer sessions</li><li><code>403</code> when trust requirements are missing</li></ul><h3 id="delete-api-folders-slug" tabindex="-1"><code>DELETE /api/folders/:slug</code> <a class="header-anchor" href="#delete-api-folders-slug" aria-label="Permalink to "`DELETE /api/folders/:slug`""></a></h3><p>Query parameters:</p><table tabindex="0"><thead><tr><th>Param</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>deleteSourceFolder</code></td><td>boolean</td><td><code>false</code></td><td>Accepts <code>true</code> or <code>false</code>.</td></tr></tbody></table><p>When <code>deleteSourceFolder=false</code>:</p><ul><li>direct posts in that folder are permanently deleted</li><li>child folders below that path are kept</li><li>Foldergram tries to remove now-empty directories</li></ul><p>When <code>deleteSourceFolder=true</code>:</p><ul><li>the source folder subtree is removed from disk</li><li>matching derivative subtrees are removed</li><li>all indexed child folders under that subtree are removed</li></ul><p>Success shape:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "slug"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"oslo"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "deletedImageCount"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">12</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "deletedFolderCount"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "deletedSourceFolder"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>404</code> with <code>{"message":"Folder not found"}</code></li><li><code>403</code> for viewer sessions</li><li><code>403</code> when trust requirements are missing</li></ul><h3 id="post-api-admin-rescan" tabindex="-1"><code>POST /api/admin/rescan</code> <a class="header-anchor" href="#post-api-admin-rescan" aria-label="Permalink to "`POST /api/admin/rescan`""></a></h3><p>Runs a manual scan against the current library and then starts the development watcher.</p><p>Success:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "ok"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "lastScan"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">7</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "status"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"completed"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "scanned_files"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">120</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Errors:</p><ul><li><code>409</code> with the library-rebuild-required message when the gallery root changed</li><li><code>403</code> for viewer sessions</li><li><code>500</code> for scan failures surfaced from the scanner</li></ul><h3 id="post-api-admin-rebuild-index" tabindex="-1"><code>POST /api/admin/rebuild-index</code> <a class="header-anchor" href="#post-api-admin-rebuild-index" aria-label="Permalink to "`POST /api/admin/rebuild-index`""></a></h3><p>Stops the watcher, clears the indexed library tables, rescans the current gallery root, and then restarts the watcher.</p><p>Matching cached derivatives already on disk are left in place and can be reused. In <code>DERIVATIVE_MODE=lazy</code>, this rebuild does not pre-generate missing thumbnails or previews.</p><p>This resets:</p><ul><li><code>likes</code></li><li><code>images</code></li><li><code>folders</code></li><li><code>folder_scan_state</code></li><li><code>scan_runs</code></li></ul><h3 id="post-api-admin-rebuild-thumbnails" tabindex="-1"><code>POST /api/admin/rebuild-thumbnails</code> <a class="header-anchor" href="#post-api-admin-rebuild-thumbnails" aria-label="Permalink to "`POST /api/admin/rebuild-thumbnails`""></a></h3><p>Stops the watcher, clears the thumbnail cache, regenerates thumbnails and video poster images from indexed media, and restarts the watcher.</p><p>It does <strong>not</strong> reset:</p><ul><li>previews</li><li>likes</li><li>folder records</li><li>scan history</li></ul><p>Errors:</p><ul><li><code>409</code> with the library-rebuild-required message when a library-index rebuild is required</li><li><code>403</code> for viewer sessions</li></ul><h2 id="client-helpers" tabindex="-1">Client helpers <a class="header-anchor" href="#client-helpers" aria-label="Permalink to "Client helpers""></a></h2><p>The frontend wraps these endpoints in <code>client/src/api/gallery.ts</code>.</p><p>Those helpers are the best reference for current client-side usage, including:</p><ul><li>default page sizes</li><li>when <code>mediaType</code> is sent</li><li>which routes are expected to return <code>items</code> arrays versus single objects</li></ul></div></div></main><footer class="VPDocFooter" data-v-7c2da6bf data-v-fea9e177><!--[--><!--]--><div class="edit-info" data-v-fea9e177><!----><div class="last-updated" data-v-fea9e177><p class="VPLastUpdated" data-v-fea9e177 data-v-61bce6e2>Last updated: <time datetime="2026-03-28T17:40:54.000Z" data-v-61bce6e2></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-fea9e177><span class="visually-hidden" id="doc-footer-aria-label" data-v-fea9e177>Pager</span><div class="pager" data-v-fea9e177><a class="VPLink link pager-link prev" href="/security" data-v-fea9e177><!--[--><span class="desc" data-v-fea9e177>Previous page</span><span class="title" data-v-fea9e177>Security</span><!--]--></a></div><div class="pager" data-v-fea9e177><a class="VPLink link pager-link next" href="/development" data-v-fea9e177><!--[--><span class="desc" data-v-fea9e177>Next page</span><span class="title" data-v-fea9e177>Development</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-b831c05f data-v-9f6e1f5c><div class="container" data-v-9f6e1f5c><p class="message" data-v-9f6e1f5c>Released under the AGPL-3.0 License.</p><p class="copyright" data-v-9f6e1f5c>Copyright © 2026 Sajjad Ali</p></div></footer><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"api.md\":\"Dq0npsCa\",\"configuration.md\":\"BsBeukw7\",\"development.md\":\"C4QAiDqM\",\"faq.md\":\"BhPUjBTn\",\"features.md\":\"C4hW69V4\",\"how-it-works.md\":\"CLbxPRcv\",\"index.md\":\"CCJ_uVDf\",\"installation.md\":\"BJPcu2wc\",\"media-processing.md\":\"BZnAue5X\",\"quick-start.md\":\"Bi2ZqhxJ\",\"security.md\":\"BwkL2X-x\",\"troubleshooting.md\":\"c84mph4l\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Foldergram\",\"description\":\"Documentation for Foldergram, the local-first photo and video gallery.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/logo.svg\",\"siteTitle\":\"Foldergram\",\"search\":{\"provider\":\"local\"},\"nav\":[{\"text\":\"Quick Start\",\"link\":\"/quick-start\"},{\"text\":\"Installation\",\"link\":\"/installation\"},{\"text\":\"Configuration\",\"link\":\"/configuration\"},{\"text\":\"How It Works\",\"link\":\"/how-it-works\"},{\"text\":\"API\",\"link\":\"/api\"},{\"text\":\"Security\",\"link\":\"/security\"},{\"text\":\"Demo\",\"link\":\"https://foldergram.intentdeep.com/\"}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/foldergram/foldergram\"}],\"sidebar\":[{\"text\":\"Guide\",\"items\":[{\"text\":\"Quick Start\",\"link\":\"/quick-start\"},{\"text\":\"Installation\",\"link\":\"/installation\"},{\"text\":\"Configuration\",\"link\":\"/configuration\"}]},{\"text\":\"Product\",\"items\":[{\"text\":\"How It Works\",\"link\":\"/how-it-works\"},{\"text\":\"Features\",\"link\":\"/features\"},{\"text\":\"Media Processing\",\"link\":\"/media-processing\"},{\"text\":\"Security\",\"link\":\"/security\"}]},{\"text\":\"Reference\",\"items\":[{\"text\":\"API\",\"link\":\"/api\"},{\"text\":\"Development\",\"link\":\"/development\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"},{\"text\":\"FAQ\",\"link\":\"/faq\"}]}],\"outline\":{\"level\":[2,3],\"label\":\"On this page\"},\"footer\":{\"message\":\"Released under the AGPL-3.0 License.\",\"copyright\":\"Copyright © 2026 Sajjad Ali\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>