Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

312 KB
Raw Blame
<!DOCTYPE html>
<!-- GENERATED FILE - do not edit by hand.
     Built by scripts/build-api-docs.mjs from api/openapi.yaml (openGym API v1.4.3).
     Regenerate with: node scripts/build-api-docs.mjs -->
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
<title>openGym: API</title>
<meta name="description" content="The complete openGym HTTP API, documented as an OpenAPI spec: passkey auth, state sync, push notifications, pairing and admin routes.">
<meta name="theme-color" content="#000000">
<meta name="robots" content="index,follow,max-image-preview:large">
<link rel="preconnect" href="https://stats.duarte-santos.ch">
<meta property="og:title" content="openGym API reference">
<meta property="og:description" content="The complete openGym HTTP API as an OpenAPI spec: passkey auth, state sync, push notifications, pairing and admin routes.">
<meta property="og:image" content="https://opengym.ch/img/social.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="openGym: your training, your data, your server. Two phones showing the home and workout screens.">
<meta property="og:url" content="https://opengym.ch/api.html">
<meta property="og:type" content="website">
<meta property="og:site_name" content="openGym">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="openGym API reference">
<meta name="twitter:image" content="https://opengym.ch/img/social.jpg">
<link rel="canonical" href="https://opengym.ch/api.html">
<link rel="icon" href="/favicon.ico" sizes="48x48">
<link rel="icon" type="image/png" sizes="96x96" href="/icon-96.png">
<link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png">
<link rel="icon" type="image/png" sizes="512x512" href="/icon-512.png">
<link rel="apple-touch-icon" href="icon-180.png">
<link rel="stylesheet" href="styles.css?v=28">
<script>document.documentElement.className += ' js'</script>
<!-- Umami web analytics for opengym.ch (self-hosted, cookieless). -->
<script defer src="https://stats.duarte-santos.ch/script.js" data-website-id="db36019e-50f4-453c-9c56-d0588aefe233"></script>
<style>
/* ------------------------------------------------------------- API reference
   Generated page. The reference itself is static HTML in the site's design.
   Layout: one 880px column of per-endpoint <details> cards. */
main.api-main { max-width: 880px; margin: 0 auto; padding: clamp(44px, 7vw, 72px) var(--pad) 0; }
main.api-main h1 { font-size: clamp(36px, 6.5vw, 60px); letter-spacing: -.03em; }
main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; font-size: clamp(16.5px, 2vw, 19px); }
.api-actions { margin-top: 26px; }
.api-actions .btn svg { width: 17px; height: 17px; }
.api-facts { display: flex; flex-wrap: wrap; gap: 6px 10px; align-items: center; margin-top: 20px; color: var(--fg-3); font-size: 13.5px; }
.api-facts span::after { content: "·"; margin-left: 10px; color: var(--fg-3); }
.api-facts span:last-child::after { content: ""; margin-left: 0; }

.api-sec { padding: 0; margin-top: clamp(46px, 7vw, 68px); }
.api-sec h2 { font-size: clamp(24px, 3.4vw, 32px); scroll-margin-top: 76px; }
.api-sec .sub { color: var(--fg-2); font-size: 15.5px; margin-top: 6px; max-width: 62ch; }
.api-sec .sub code, .ov code, .ep-auth code {
  background: var(--surface-2); border-radius: 5px; padding: 1.5px 5px; font-size: .85em; color: #e4e4e8;
}

/* base URLs */
.srv { margin-top: 20px; border: 1px solid var(--hair-soft); border-radius: var(--r-s); background: var(--surface); overflow: hidden; }
.srv-row { display: flex; flex-wrap: wrap; gap: 2px 16px; align-items: baseline; padding: 12px 16px; }
.srv-row + .srv-row { border-top: 1px solid var(--hair-soft); }
.srv-row > code { font-size: 13.5px; color: var(--acc); }
.srv-row > span { color: var(--fg-3); font-size: 13.5px; }

/* overview cards (from the spec's info sections) */
/* align-items:start, so a short card stops at its own last line instead of
   stretching to its neighbour's height and showing a panel of empty background. */
.ov-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); align-items: start; gap: 12px; margin-top: 18px; }
.ov { background: var(--surface); border: 1px solid var(--hair-soft); border-radius: var(--r-m); padding: 20px 22px; }
.ov h3 { font-size: 15.5px; margin-bottom: 8px; }
.ov p, .ov li { color: var(--fg-2); font-size: 14px; line-height: 1.55; }
.ov p + p, .ov p + ul { margin-top: 8px; }
.ov ul { padding-left: 18px; margin: 0; }
.ov li { margin: 5px 0; }
.ov li::marker { color: var(--fg-3); }
.ov:last-child:nth-child(odd) { grid-column: 1 / -1; }
@media (max-width: 720px) { .ov-grid { grid-template-columns: 1fr; } }

/* expand / collapse all */
.xall { display: flex; gap: 16px; justify-content: flex-end; margin: 30px 0 -34px; }
.xall button { color: var(--fg-3); font-size: 13px; cursor: pointer; padding: 4px 0; transition: color .2s var(--ease); }
.xall button:hover { color: var(--fg); }

/* endpoint + schema cards */
.eps { margin-top: 16px; display: flex; flex-direction: column; gap: 8px; }
.ep { background: var(--surface); border: 1px solid var(--hair-soft); border-radius: var(--r-s); scroll-margin-top: 70px; transition: border-color .25s var(--ease); }
.ep:hover, .ep[open] { border-color: var(--hair); }
.ep > summary { list-style: none; cursor: pointer; padding: 12px 16px; display: grid; grid-template-columns: auto minmax(0, 1fr) auto; column-gap: 12px; row-gap: 2px; align-items: center; }
.ep > summary::-webkit-details-marker { display: none; }
.m { justify-self: start; min-width: 52px; text-align: center; padding: 3px 8px; border-radius: 7px; font-size: 11px; font-weight: 700; letter-spacing: .05em; font-family: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; }
.m.get { color: #6cb2ff; background: rgba(108, 178, 255, .12); }
.m.post { color: var(--acc); background: var(--acc-soft); }
.m.put { color: #ffb340; background: rgba(255, 159, 10, .14); }
.m.delete, .m.patch { color: #ff6b5e; background: rgba(255, 80, 60, .12); }
.ep-path { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; min-width: 0; }
.ep-path code, .sch-name code { font-size: 13.5px; color: var(--fg); word-break: break-all; }
.ep-chip { font-size: 10px; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; padding: 2px 7px; border-radius: 6px; }
.ep-chip.public { color: var(--fg-2); background: rgba(255, 255, 255, .07); }
.ep-chip.admin { color: #ffb340; background: rgba(255, 159, 10, .12); }
.ep-chev { width: 8px; height: 8px; border-right: 1.6px solid var(--fg-3); border-bottom: 1.6px solid var(--fg-3); transform: rotate(45deg) translate(-1px, -1px); transition: transform .25s var(--ease); }
.ep[open] > summary .ep-chev { transform: rotate(225deg); }
.ep-sum { grid-column: 2 / -1; color: var(--fg-3); font-size: 13.5px; line-height: 1.45; }
.ep-body { border-top: 1px solid var(--hair-soft); padding: 16px 16px 18px; }
/* WebAuthn type names run to 34 characters. On a phone they are wider than the
   card, so every prose block in here is allowed to break inside a word. */
.ep-body > p, .ep-body > ul li, .ov p, .ov li, .p-desc, .api-sec .sub, .ep-auth,
.ep-path code, .sch-name code, .p-name, .p-type { overflow-wrap: break-word; }
.ep-body > p { color: var(--fg-2); font-size: 14.5px; line-height: 1.65; margin: 0 0 10px; max-width: 74ch; }
.ep-body > ul { margin: 0 0 10px; padding-left: 20px; }
.ep-body > ul li { color: var(--fg-2); font-size: 14.5px; line-height: 1.65; margin: 4px 0; }
/* Identifiers are half of every sentence in an API description: as full chips they
   turn a paragraph into confetti, so here they are monospace with a hairline tint. */
.ep-body p code, .ep-body li code, .ov p code, .ov li code, .api-sec .sub code,
.ep-auth code, .p-desc code {
  background: rgba(255, 255, 255, .05); border-radius: 4px; padding: 0 3px;
  font-size: .9em; line-height: inherit; color: #d8dee2;
}
/* Grid, not flex: the sentence wraps around code chips, and a flex row would
   centre the whole wrapped block against the padlock and stagger the lines. */
.ep-auth { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: start; gap: 8px; color: var(--fg-3); font-size: 13px; line-height: 1.6; margin: 14px 0 0 !important; }
.ep-auth svg { width: 13px; height: 13px; margin-top: 3px; }
.ep-h { font-size: 11.5px; font-weight: 600; letter-spacing: .08em; text-transform: uppercase; color: var(--fg-3); margin: 18px 0 8px !important; }
.p-hint { color: var(--fg-3); font-weight: 400; text-transform: none; letter-spacing: 0; }

/* parameter / response tables */
.ptab { border: 1px solid var(--hair-soft); border-radius: 10px; overflow: hidden; }
.prow { display: grid; grid-template-columns: minmax(140px, 220px) minmax(110px, 200px) 1fr; gap: 3px 14px; padding: 10px 14px; font-size: 13.5px; }
.prow + .prow { border-top: 1px solid var(--hair-soft); }
.p-name { font-family: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; color: var(--fg); word-break: break-all; }
.p-req { font-style: normal; color: #ffb340; font-size: 10.5px; margin-left: 7px; letter-spacing: .04em; }
.p-type { font-family: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; color: var(--fg-3); word-break: break-word; }
.p-type a, .r-sig a, .p-desc a { color: var(--acc); }
.p-desc { color: var(--fg-2); line-height: 1.5; }
.rrow { grid-template-columns: 44px 1fr; }
.r-code { font-family: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; font-weight: 600; }
.r-code.s2 { color: var(--acc); } .r-code.s3 { color: #6cb2ff; }
.r-code.s4 { color: #ffb340; } .r-code.s5 { color: #ff6b5e; }
.r-sig { display: block; margin-top: 4px; font-family: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace; font-size: 11.5px; color: var(--fg-3); word-break: break-word; line-height: 1.6; }
.r-sig code, .p-type code { background: none; padding: 0; color: inherit; font-size: inherit; }
.ep-body pre { margin: 8px 0 2px; padding: 12px 14px; font-size: 12.5px; }
@media (max-width: 680px) {
  .prow { grid-template-columns: minmax(0, 1fr) auto; }
  .prow .p-desc { grid-column: 1 / -1; margin-top: 1px; }
  .rrow { grid-template-columns: 44px 1fr; }
  .rrow .p-desc { grid-column: auto; margin-top: 0; }
}

/* schema cards */
.sch > summary { grid-template-columns: minmax(0, 1fr) auto; }
.sch .ep-sum { grid-column: 1 / -1; }

/* The header, the navigation sheet and the contents drawer belong to the site, not
   to this page: .navsheet, .toc-btn, .side and .rail-close live in styles.css and
   site.js and behave identically here, on the docs page and on the home page. This
   file deliberately adds nothing of its own to them. One implementation is the
   only way the two rail pages can feel like the same rail. */
</style>
</head>
<body class="topnav dock">
<a class="skip" href="#main">Skip to content</a>

<nav><div class="wrap nav-in">
  <a class="brand" href="/">
    <img src="icon-180.png" alt="" width="24" height="24">
    openGym
  </a>
  <div class="nav-quick">
    <a class="ql site" href="/#features">Features</a>
    <a class="ql site" href="/#screens">Screenshots</a>
    <a class="ql site" href="/#demo">Demo</a>
    <a class="ql site" href="/docs.html">Docs</a>
    <a class="ql site" href="/api.html">API</a>
    <a class="ql site" href="/about.html">About</a>
    <a class="ql" href="https://github.com/DuarteSantos8/openGym" rel="noopener">GitHub <span data-gh="stars"></span></a>
    <a class="ql" href="https://discord.gg/e62jY6fwVb" rel="noopener">Discord <span data-dc="members"></span></a>
    <a class="ql coffee" href="https://buymeacoffee.com/duartesantos" rel="noopener" aria-label="Buy me a coffee"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M20.216 6.415l-.132-.666c-.119-.598-.388-1.163-1.001-1.379-.197-.069-.42-.098-.57-.241-.152-.143-.196-.366-.231-.572-.065-.378-.125-.756-.192-1.133-.057-.325-.102-.69-.25-.987-.195-.4-.597-.634-.996-.788a5.723 5.723 0 00-.626-.194c-1-.263-2.05-.36-3.077-.416a25.834 25.834 0 00-3.7.062c-.915.083-1.88.184-2.75.5-.318.116-.646.256-.888.501-.297.302-.393.77-.177 1.146.154.267.415.456.692.58.36.162.737.284 1.123.366 1.075.238 2.189.331 3.287.37 1.218.05 2.437.01 3.65-.118.299-.033.598-.073.896-.119.352-.054.578-.513.474-.834-.124-.383-.457-.531-.834-.473-.466.074-.96.108-1.382.146-1.177.08-2.358.082-3.536.006a22.228 22.228 0 01-1.157-.107c-.086-.01-.18-.025-.258-.036-.243-.036-.484-.08-.724-.13-.111-.027-.111-.185 0-.212h.005c.277-.06.557-.108.838-.147h.002c.131-.009.263-.032.394-.048a25.076 25.076 0 013.426-.12c.674.019 1.347.067 2.017.144l.228.031c.267.04.533.088.798.145.392.085.895.113 1.07.542.055.137.08.288.111.431l.319 1.484a.237.237 0 01-.199.284h-.003c-.037.006-.075.01-.112.015a36.704 36.704 0 01-4.743.295 37.059 37.059 0 01-4.699-.304c-.14-.017-.293-.042-.417-.06-.326-.048-.649-.108-.973-.161-.393-.065-.768-.032-1.123.161-.29.16-.527.404-.675.701-.154.316-.199.66-.267 1-.069.34-.176.707-.135 1.056.087.753.613 1.365 1.37 1.502a39.69 39.69 0 0011.343.376.483.483 0 01.535.53l-.071.697-1.018 9.907c-.041.41-.047.832-.125 1.237-.122.637-.553 1.028-1.182 1.171-.577.131-1.165.2-1.756.205-.656.004-1.31-.025-1.966-.022-.699.004-1.556-.06-2.095-.58-.475-.458-.54-1.174-.605-1.793l-.731-7.013-.322-3.094c-.037-.351-.286-.695-.678-.678-.336.015-.718.3-.678.679l.228 2.185.949 9.112c.147 1.344 1.174 2.068 2.446 2.272.742.12 1.503.144 2.257.156.966.016 1.942.053 2.892-.122 1.408-.258 2.465-1.198 2.616-2.657.34-3.332.683-6.663 1.024-9.995l.215-2.087a.484.484 0 01.39-.426c.402-.078.787-.212 1.074-.518.455-.488.546-1.124.385-1.766zm-1.478.772c-.145.137-.363.201-.578.233-2.416.359-4.866.54-7.308.46-1.748-.06-3.477-.254-5.207-.498-.17-.024-.353-.055-.47-.18-.22-.236-.111-.71-.054-.995.052-.26.152-.609.463-.646.484-.057 1.046.148 1.526.22.577.088 1.156.159 1.737.212 2.48.226 5.002.19 7.472-.14.45-.06.899-.13 1.345-.21.399-.072.84-.206 1.08.206.166.281.188.657.162.974a.544.544 0 01-.169.364zm-6.159 3.9c-.862.37-1.84.788-3.109.788a5.884 5.884 0 01-1.569-.217l.877 9.004c.065.78.717 1.38 1.5 1.38 0 0 1.243.065 1.658.065.447 0 1.786-.065 1.786-.065.783 0 1.434-.6 1.499-1.38l.94-9.95a3.996 3.996 0 00-1.322-.238c-.826 0-1.491.284-2.26.613z"/></svg><span>Buy me a coffee!</span></a>
    <a class="cta" href="/#download">Download</a>
  </div>
  <button class="nav-toggle" id="navtoggle" aria-expanded="false" aria-controls="sitemenu" aria-label="Menu">
    <span></span><span></span>
  </button>
</div></nav>

<!-- The navigation sheet: the header's links again, for the widths where the bar has
     room only for the brand and the download. Byte-identical on every page, like the
     bar above it, so nothing is ever dropped because of which page you are on. -->
<div class="navsheet" id="sitemenu" role="navigation" aria-label="Site" aria-hidden="true">
  <div class="nl-rows">
    <a class="nl" href="/#features">Features</a>
    <a class="nl" href="/#screens">Screenshots</a>
    <a class="nl" href="/#demo">Demo</a>
    <a class="nl" href="/docs.html">Docs</a>
    <a class="nl" href="/api.html">API</a>
    <a class="nl" href="/about.html">About</a>
    <a class="nl" href="https://github.com/DuarteSantos8/openGym" rel="noopener">GitHub <span data-gh="stars"></span></a>
    <a class="nl" href="https://discord.gg/e62jY6fwVb" rel="noopener">Discord <span data-dc="members"></span></a>
    <a class="nl coffee" href="https://buymeacoffee.com/duartesantos" rel="noopener">Buy me a coffee! <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M20.216 6.415l-.132-.666c-.119-.598-.388-1.163-1.001-1.379-.197-.069-.42-.098-.57-.241-.152-.143-.196-.366-.231-.572-.065-.378-.125-.756-.192-1.133-.057-.325-.102-.69-.25-.987-.195-.4-.597-.634-.996-.788a5.723 5.723 0 00-.626-.194c-1-.263-2.05-.36-3.077-.416a25.834 25.834 0 00-3.7.062c-.915.083-1.88.184-2.75.5-.318.116-.646.256-.888.501-.297.302-.393.77-.177 1.146.154.267.415.456.692.58.36.162.737.284 1.123.366 1.075.238 2.189.331 3.287.37 1.218.05 2.437.01 3.65-.118.299-.033.598-.073.896-.119.352-.054.578-.513.474-.834-.124-.383-.457-.531-.834-.473-.466.074-.96.108-1.382.146-1.177.08-2.358.082-3.536.006a22.228 22.228 0 01-1.157-.107c-.086-.01-.18-.025-.258-.036-.243-.036-.484-.08-.724-.13-.111-.027-.111-.185 0-.212h.005c.277-.06.557-.108.838-.147h.002c.131-.009.263-.032.394-.048a25.076 25.076 0 013.426-.12c.674.019 1.347.067 2.017.144l.228.031c.267.04.533.088.798.145.392.085.895.113 1.07.542.055.137.08.288.111.431l.319 1.484a.237.237 0 01-.199.284h-.003c-.037.006-.075.01-.112.015a36.704 36.704 0 01-4.743.295 37.059 37.059 0 01-4.699-.304c-.14-.017-.293-.042-.417-.06-.326-.048-.649-.108-.973-.161-.393-.065-.768-.032-1.123.161-.29.16-.527.404-.675.701-.154.316-.199.66-.267 1-.069.34-.176.707-.135 1.056.087.753.613 1.365 1.37 1.502a39.69 39.69 0 0011.343.376.483.483 0 01.535.53l-.071.697-1.018 9.907c-.041.41-.047.832-.125 1.237-.122.637-.553 1.028-1.182 1.171-.577.131-1.165.2-1.756.205-.656.004-1.31-.025-1.966-.022-.699.004-1.556-.06-2.095-.58-.475-.458-.54-1.174-.605-1.793l-.731-7.013-.322-3.094c-.037-.351-.286-.695-.678-.678-.336.015-.718.3-.678.679l.228 2.185.949 9.112c.147 1.344 1.174 2.068 2.446 2.272.742.12 1.503.144 2.257.156.966.016 1.942.053 2.892-.122 1.408-.258 2.465-1.198 2.616-2.657.34-3.332.683-6.663 1.024-9.995l.215-2.087a.484.484 0 01.39-.426c.402-.078.787-.212 1.074-.518.455-.488.546-1.124.385-1.766zm-1.478.772c-.145.137-.363.201-.578.233-2.416.359-4.866.54-7.308.46-1.748-.06-3.477-.254-5.207-.498-.17-.024-.353-.055-.47-.18-.22-.236-.111-.71-.054-.995.052-.26.152-.609.463-.646.484-.057 1.046.148 1.526.22.577.088 1.156.159 1.737.212 2.48.226 5.002.19 7.472-.14.45-.06.899-.13 1.345-.21.399-.072.84-.206 1.08.206.166.281.188.657.162.974a.544.544 0 01-.169.364zm-6.159 3.9c-.862.37-1.84.788-3.109.788a5.884 5.884 0 01-1.569-.217l.877 9.004c.065.78.717 1.38 1.5 1.38 0 0 1.243.065 1.658.065.447 0 1.786-.065 1.786-.065.783 0 1.434-.6 1.499-1.38l.94-9.95a3.996 3.996 0 00-1.322-.238c-.826 0-1.491.284-2.26.613z"/></svg></a>
  </div>
</div>

<!-- The one control that opens the contents, at every width. The drawer it opens is
     closed in CSS, so it is shut on first paint whether or not the script runs. -->
<button class="toc-btn" id="tocbtn" aria-expanded="false" aria-controls="menu">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" aria-hidden="true"><path d="M4 6.5h16M4 12h16M4 17.5h10"/></svg>
  Contents
</button>

<!-- The contents drawer: one list, one way in, one way out. Closed by default at
     every width, and no preference is remembered. See .side in styles.css. -->
<aside class="side" id="menu" aria-label="Contents" aria-hidden="true">
  <div class="side-top">
    <p class="side-title">Contents</p>
    <button class="rail-close" aria-label="Close contents"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M5 5l14 14M19 5L5 19"/></svg></button>
  </div>
  <p class="side-label">On this page</p>
  <a class="side-link" href="#overview"><b>Overview</b><span>Auth model, sessions, conventions</span></a>
  <a class="side-link" href="#meta"><b>Meta</b><span>Health &amp; public config</span></a>
  <a class="side-link" href="#auth"><b>Auth</b><span>Passkeys &amp; sessions</span></a>
  <a class="side-link" href="#pairing"><b>Pairing</b><span>Connect the mobile app</span></a>
  <a class="side-link" href="#password"><b>Password</b><span>Optional name &amp; password (PASSWORD_LOGIN)</span></a>
  <a class="side-link" href="#passkeys"><b>Passkeys</b><span>More passkeys &amp; device links</span></a>
  <a class="side-link" href="#data"><b>Data</b><span>State sync</span></a>
  <a class="side-link" href="#push"><b>Push</b><span>Notifications &amp; rest timer</span></a>
  <a class="side-link" href="#activity"><b>Activity</b><span>Live presence</span></a>
  <a class="side-link" href="#media"><b>Media</b><span>Photos &amp; videos of your exercises &amp; workouts</span></a>
  <a class="side-link" href="#coach"><b>AI Coach</b><span>Plans, reviews, debriefs</span></a>
  <a class="side-link" href="#admin"><b>Admin</b><span>Users, invites, audit log, Coach</span></a>
  <a class="side-link" href="#schemas"><b>Schemas</b><span>The state blob, the error shape &amp; co.</span></a>
  <p class="side-label">More</p>
  <a class="side-link" href="/"><b>Home</b><span>The tour, the demo, the download</span></a>
  <a class="side-link" href="/docs.html"><b>Docs</b><span>Install, self-host, import</span></a>
  <a class="side-link" href="/about.html"><b>About</b><span>The story and the milestones</span></a>
</aside>

<main id="main" class="api-main">
  <h1>API</h1>
  <p class="lead">Every route the openGym backend serves (passkey auth, state sync,
     push, pairing, admin) as one hand-written
     OpenAPI&nbsp;spec. The same file lives
     <a href="https://github.com/DuarteSantos8/openGym/blob/main/api/openapi.yaml" rel="noopener">in the repository</a>
     at <code>api/openapi.yaml</code>, next to the one server file it documents.</p>
  <div class="actions api-actions">
    <a class="btn" href="openapi.yaml" download>
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12m0 0l-5-5m5 5l5-5M4 19h16"/></svg>
      Download openapi.yaml</a>
  </div>
  <p class="api-facts">
    <span>OpenAPI 3.1.0</span>
    <span>openGym v1.4.3</span>
    <span>75 endpoints</span>
    <span>AGPL-3.0-or-later</span>
  </p>

  <section class="api-sec" id="overview">
    <h2>Overview</h2>
    <p class="sub">Passkey (WebAuthn) auth + per-user state storage for openGym. One Node file, no framework, JSON-file
       storage, HMAC-signed session cookies.</p>
    <div class="srv">
  <div class="srv-row"><code>/</code><span>Same origin as the openGym web app (the normal deployment)</span></div>
  <div class="srv-row"><code>https://opengym.example.com</code><span>Your self-hosted instance</span></div>
    </div>
    <div class="ov-grid">
  <div class="ov">
    <h3>Authentication</h3>
<p>Sign-in is by <b>passkey</b> (WebAuthn, via <code>@simplewebauthn/server</code>). A successful <code>register/verify</code> or <code>login/verify</code> sets the session cookie; every authenticated route then works with that cookie. The paired mobile app has no shared cookie jar, so it redeems a short pairing code (<code>/api/pair/redeem</code>) for the <i>same</i> signed token and sends it as <code>Authorization: Bearer &lt;token&gt;</code> instead.</p>
<p>An instance started with <code>PASSWORD_LOGIN=1</code> also offers <b>name-and-password sign-in</b> (tag <code>password</code>): opt-in per profile, scrypt-hashed, throttled, with an admin-issued one-time reset code instead of e-mail. A profile may also add an e-mail address to sign in with instead of its name (<code>/api/account/email</code>); no mail is ever sent to it. Its routes set exactly the same cookie. With the flag off (the default) every one of them answers 404.</p>
  </div>
  <div class="ov">
    <h3>Throttling</h3>
<p>The <code>password</code> routes are counted per client address: at most 60 requests a minute across them, and wrong answers (a password, a reset code, an invite code on password signup, an e-mail address already in use) pause the address from the 21st on, for 30 s, doubling up to 15 min. Wrong passwords also pause the <i>account</i> they were tried against from the 6th on, for 1 min doubling up to 1 h (the same pause whether the account was named by its name or its e-mail), and an identifier that names no account is paused the same way, as typed. A password check counts from the moment it starts, so checks sent at once get no more tries than checks sent one by one. A paused caller gets <code>429 {&quot;error&quot;: …, &quot;code&quot;: &quot;locked&quot;, &quot;retryAfter&quot;: &lt;s&gt;}</code> with a <code>Retry-After</code> header. Passkey sign-up and sign-in and the pairing routes are not throttled (their failures reach the audit log at most ten a minute per address). The two routes that redeem a one-time device link (tag <code>passkeys</code>) share the per-address budget, and wrong codes pause the address for link redemption only, from the 21st on, the way wrong reset codes do. Adding or removing a passkey in Settings (<code>POST /api/account/passkeys/options</code>, <code>DELETE /api/account/passkeys</code>) and making a device code (<code>POST /api/account/device-link</code>) spend the per-address budget too, and a current password given there as proof counts like one given at sign-in. The address is the socket's, or with <code>TRUST_PROXY=1</code> the one a trusted proxy put in <code>CF-Connecting-IP</code> / the last <code>X-Forwarded-For</code> entry / <code>X-Real-IP</code>; IPv6 clients are counted by /64. Counters live in memory and reset on restart.</p>
  </div>
  <div class="ov">
    <h3>Sessions</h3>
<p>The cookie/bearer value is <code>&lt;payload&gt;.&lt;hmac&gt;</code> where the payload is <code>&lt;uid&gt;:&lt;expiry-ms&gt;:&lt;session-version&gt;</code>, signed with a per-instance secret (HMAC-SHA256). Sessions last <code>SESSION_DAYS</code> (default 90). <code>POST /api/logout/all</code> bumps the user's session version, which invalidates every token ever issued for the account.</p>
  </div>
  <div class="ov">
    <h3>CSRF</h3>
<p>State-changing browser requests must come from the app's own origin. The server checks <code>Sec-Fetch-Site</code> (falling back to <code>Origin</code> vs the configured <code>ORIGIN</code>); a mismatch is refused with <code>403 {&quot;error&quot;:&quot;cross-origin request refused&quot;,&quot;code&quot;:&quot;origin-mismatch&quot;,&quot;expected&quot;:ORIGIN}</code> on any non-GET route, the passkey routes included. Exempt: <code>pair/redeem</code>, which the mobile app calls from its own origin (the code in the body is the credential, and the token comes back in the body, never as a cookie), and any request a Bearer token authenticates by itself: a valid session token, with no session cookie beside it, on any route but the sign-in ones — the four passkey routes, the password and reset-code routes and the two device-link routes, which act on the credential in the body, never on a Bearer. A cross-origin request whose Bearer does not buy the exemption is refused before any handler runs: <code>401 {&quot;error&quot;:&quot;not signed in&quot;}</code> when that Bearer does not verify and is the only credential (a paired app whose token was revoked or expired), the 403 otherwise. The passkey routes were exempt before, on the grounds that the challenge id is a credential; but it is bound to nothing else, so a hostile page could complete the attacker's own passkey sign-in in the victim's browser (login CSRF) and the answer set the victim's session to the attacker's account. The password routes are <b>not</b> exempt for the same reason: a hostile page knows a valid name and password of its own.</p>
  </div>
  <div class="ov">
    <h3>Environment-dependent behavior</h3>
<ul><li><code>INVITE_ONLY=1</code>: registration requires a valid invite code (minted by an admin).</li><li><code>ALLOW_GUEST=0</code>: hides the client-side &quot;continue without account&quot; mode; the server merely reports the flag via <code>GET /api/config</code> (guest mode never talks to this API at all).</li><li><code>ADMIN_UIDS=&lt;uid&gt;,&lt;uid&gt;</code>: user ids treated as admins (a <code>&quot;admin&quot;: true</code> flag on the user record in <code>db.json</code> works too). Admins get the <code>/api/admin/*</code> routes. One admin is the owner: the record with <code>&quot;owner&quot;: true</code>, else the first <code>ADMIN_UIDS</code> entry with a profile, else the oldest admin. Only the owner appoints and removes admins, deletes an admin, hands the role on and clears the audit log.</li><li><code>FIRST_USER_ADMIN</code> (default off; <code>1</code> turns it on): the first profile registered on an instance with no profiles gets that <code>&quot;admin&quot;: true</code> flag and is the owner. Decided at registration only, never applied to an instance that already has profiles.</li><li><code>AUDIT_LOG</code> (default on), <code>AUDIT_MAX</code> (default 5000 events), <code>AUDIT_DAYS</code> (default 90), <code>AUDIT_IP</code> (<code>off</code> | <code>net</code> | <code>full</code>, default off) shape the audit log served by <code>GET /api/admin/audit</code>.</li><li><code>PASSWORD_LOGIN=1</code>: adds the <code>password</code> routes and <code>password_login: true</code> in <code>GET /api/config</code>. Off by default.</li><li><code>DEFAULT_LANG</code> (e.g. <code>pt-BR</code>; unset by default): <code>default_lang</code> in <code>GET /api/config</code>, the language of the sign-in screen and of every profile that never picked one.</li><li><code>TRUST_PROXY=1</code>: the throttle reads the client address from proxy headers (set by the bundled <code>docker-compose.yml</code>, where only the web container can reach the API).</li><li><code>MEDIA_UPLOADS</code> (default on; <code>0</code> removes the <code>media</code> routes and the <code>media</code> block of <code>GET /api/config</code>), <code>MEDIA_QUOTA_MB</code> (200 per profile, <code>0</code> = no cap), <code>MEDIA_IMAGE_MAX_MB</code> (2), <code>MEDIA_GIF_MAX_MB</code> (8), <code>MEDIA_VIDEO_MAX_MB</code> (40), <code>MEDIA_VIDEO_MAX_SEC</code> (60), <code>MEDIA_GC_GRACE_DAYS</code> (14), <code>MEDIA_UPLOADS_PER_HOUR</code> (600 per profile), <code>MEDIA_MIN_FREE_MB</code> (512, <code>0</code> = no floor): photos and videos of custom exercises (tag <code>media</code>). Every MB here is 2^20 bytes.</li></ul>
  </div>
  <div class="ov">
    <h3>Conventions</h3>
<ul><li>Every response body is JSON with <code>Cache-Control: no-store</code>. The one exception is <code>GET /api/media/{hash}</code>, which answers with the stored file itself (<code>Cache-Control: private, no-store</code>).</li><li>Errors are always <code>{&quot;error&quot;: &quot;&lt;human-readable message&gt;&quot;}</code>. The <code>password</code>, throttle and <code>media</code> routes add a stable <code>code</code> for the client to word in its own language.</li><li>Unknown method+path pairs return <code>404 {&quot;error&quot;:&quot;not found&quot;}</code>; an unhandled exception returns <code>500 {&quot;error&quot;:&quot;server error&quot;}</code>.</li><li>Every route that reads a request body requires <code>Content-Type: application/json</code> (a <code>charset</code> parameter is fine) and answers any other type with <code>415 {&quot;error&quot;:&quot;content-type must be application/json&quot;}</code> — the types a form can send are the ones that skip the CORS preflight, which is how a cross-site form reached these routes. A request with no body needs no Content-Type. A body that does not parse, or parses to anything but an object (<code>null</code>, a string, an array), is <code>400 {&quot;error&quot;:&quot;invalid json&quot;}</code> on every route that reads one; an empty body counts as <code>{}</code>. A body over 5 MiB is <code>413 {&quot;error&quot;:&quot;body too large&quot;}</code>; the rest of the upload is discarded so the answer reaches the client.</li><li>CORS: the request's <code>Origin</code> is reflected in <code>Access-Control-Allow-Origin</code> <b>without</b> <code>Allow-Credentials</code>, so cross-origin callers can only ever authenticate with a Bearer token, never with the cookie.</li></ul>
  </div>
    </div>
  </section>

  <div class="xall" aria-label="Card controls">
    <button data-xall="1">Expand all</button>
    <button data-xall="0">Collapse all</button>
  </div>

<section class="api-sec" id="meta">
  <h2>Meta</h2>
  <p class="sub">Health and public configuration</p>
  <div class="eps">

<details class="ep" id="op-getHealth">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/health</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Health check</span>
  </summary>
  <div class="ep-body">
<p>Always public. Also reports how many user accounts exist.</p>
<p>The check writes: it creates and removes one empty file under <code>DATA_DIR</code>, because a server whose data directory is full or read-only has every write path broken while the port still answers. It is a 503 when that fails — the container healthcheck (<code>wget --spider</code>) reads the status and nothing else.</p>
<p>The probe runs at most once every five seconds and the answer in between is the last one, so a poll can be that stale. The route is unauthenticated, and one disk write per request is not something to leave open to anyone.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The server is up and its data directory is writable.<span class="r-sig">{ ok: always true, users: integer, writable: always true }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The data directory could not be written — a full disk, or a mount that came back read-only. Nothing that stores anything will work until it is fixed; the reason is in the container log.</span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getConfig">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/config</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Instance configuration</span>
  </summary>
  <div class="ep-body">
<p>The flags the login screen needs before anyone is signed in. Both reflect environment variables on the server (<code>INVITE_ONLY</code>, <code>ALLOW_GUEST</code>), and so does <code>password_login</code>, which is there only when <code>PASSWORD_LOGIN=1</code>, and <code>default_lang</code>, which is there only when <code>DEFAULT_LANG</code> is set.</p>
<p><code>media</code> is there unless the instance runs with <code>MEDIA_UPLOADS=0</code>, for everybody: the caps are not a secret, and its absence is how the app knows this server does not store photos and videos at all.</p>
<p>A caller with a valid session also gets a <code>coach</code> key: the block when the instance has the AI Coach switched on <b>and</b> a provider connected, and <code>null</code> when it has not. A caller with no session gets no key at all. The block names the provider this instance talks to, which is the same fact <code>GET /api/coach/disclosure</code> will not hand out unauthenticated.</p>
<p>The key is always present for a session, <code>null</code> included, so a client that caches this answer can tell &quot;no Coach on this instance&quot; from &quot;you were not signed in when you asked&quot; and knows whether asking again would change it.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Instance flags, plus the Coach block for a signed-in caller.<span class="r-sig">{ invite_only: boolean, allow_guest: boolean, coach: object | null, password_login: always true, default_lang: string, media: <a href="#schema-MediaConfig">MediaConfig</a> }</span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="auth">
  <h2>Auth</h2>
  <p class="sub">Passkey (WebAuthn) registration and login, sessions</p>
  <div class="eps">

<details class="ep" id="op-getMe">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/me</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Who am I?</span>
  </summary>
  <div class="ep-body">
<p>Resolves the current session to a user. A paired phone (bearer token) whose token is past half of <code>SESSION_DAYS</code> also receives a fresh <code>token</code> to use from now on; it carries the account's current session version, so &quot;sign out everywhere&quot; revokes it like the old one. Cookie sessions never get one.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">A valid session.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a>, token: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-registerOptions">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/register/options</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Start passkey registration (WebAuthn ceremony, step 1)</span>
  </summary>
  <div class="ep-body">
<p>Returns <code>PublicKeyCredentialCreationOptions</code> (from <code>@simplewebauthn/server</code>'s <code>generateRegistrationOptions</code>) plus a challenge id <code>cid</code>. The client passes <code>options</code> to <code>navigator.credentials.create()</code> (or <code>@simplewebauthn/browser</code>'s <code>startRegistration</code>) and sends the result to <code>/api/register/verify</code> together with the <code>cid</code>. Challenges are one-shot and expire after 5 minutes.</p>
<p>No session required.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">name<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc">Display name for the new profile (trimmed, max 40 chars).</span>
  </div>
  <div class="prow">
    <span class="p-name">code</span>
    <span class="p-type">string</span>
    <span class="p-desc">Invite code, required (and validated) only when the instance runs with INVITE_ONLY. Compared case-insensitively.</span>
  </div>
</div>
<pre><code>{
  &quot;name&quot;: &quot;Ada&quot;,
  &quot;code&quot;: &quot;3F9C21A07B54D688&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Ceremony options.<span class="r-sig">{ cid: string, options: <a href="#schema-WebAuthnRegistrationOptions">WebAuthnRegistrationOptions</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>name</code> missing/empty.<span class="r-sig"><code>{&quot;error&quot;:&quot;name required&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Instance is invite-only and the code is missing, used, or revoked.<span class="r-sig"><code>{&quot;error&quot;:&quot;a valid invite code is required&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-registerVerify">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/register/verify</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Finish passkey registration (WebAuthn ceremony, step 2)</span>
  </summary>
  <div class="ep-body">
<p>Verifies the authenticator's attestation response against the stored challenge (<code>verifyRegistrationResponse</code>), creates the user + credential, and signs the caller in (sets the session cookie). On an invite-only instance the invite is re-checked and burned here.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">cid<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The challenge id from /api/register/options.</span>
  </div>
  <div class="prow">
    <span class="p-name">credential<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-WebAuthnRegistrationCredential">WebAuthnRegistrationCredential</a></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Registered and signed in. The session cookie is set.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Challenge expired/replayed, or the attestation did not verify (wrong origin/RP ID, malformed response…). The message is human-readable.<span class="r-sig"><code>{&quot;error&quot;:&quot;challenge expired, try again&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Invite-only and the code became invalid since step 1.<span class="r-sig"><code>{&quot;error&quot;:&quot;invite code is no longer valid, ask for a new one&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">This credential id is already registered.<span class="r-sig"><code>{&quot;error&quot;:&quot;credential already registered&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-loginOptions">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/login/options</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Start passkey login (WebAuthn ceremony, step 1)</span>
  </summary>
  <div class="ep-body">
<p>Returns <code>PublicKeyCredentialRequestOptions</code> (<code>generateAuthenticationOptions</code> with an empty <code>allowCredentials</code>; discoverable credentials / resident keys are required at registration, so the browser offers the user their passkeys itself) plus a one-shot challenge id <code>cid</code>. Takes no request body.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Ceremony options.<span class="r-sig">{ cid: string, options: <a href="#schema-WebAuthnAuthenticationOptions">WebAuthnAuthenticationOptions</a> }</span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-loginVerify">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/login/verify</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Finish passkey login (WebAuthn ceremony, step 2)</span>
  </summary>
  <div class="ep-body">
<p>Verifies the assertion (<code>verifyAuthenticationResponse</code>), updates the signature counter, and signs the caller in (sets the session cookie).</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">cid<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The challenge id from /api/login/options.</span>
  </div>
  <div class="prow">
    <span class="p-name">credential<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-WebAuthnAuthenticationCredential">WebAuthnAuthenticationCredential</a></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Signed in. The session cookie is set.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Challenge expired/replayed, or the assertion did not verify.<span class="r-sig"><code>{&quot;error&quot;:&quot;not verified&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The account has been disabled by an admin.<span class="r-sig"><code>{&quot;error&quot;:&quot;this account has been disabled&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">The passkey's credential id is unknown to this instance.<span class="r-sig"><code>{&quot;error&quot;:&quot;unknown passkey, create a profile first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">500</span>
    <span class="p-desc">Credential exists but its user record is missing (corrupt db).<span class="r-sig"><code>{&quot;error&quot;:&quot;user missing&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-logout">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/logout</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Sign out (this device)</span>
  </summary>
  <div class="ep-body">
<p>Clears the session cookie. Always succeeds: an invalid or missing session is a no-op. The token itself stays cryptographically valid until it expires; use /api/logout/all to revoke tokens.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Cookie cleared.<span class="r-sig"><a href="#schema-Ok">Ok</a> &middot; sets <code>Set-Cookie</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-logoutAll">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/logout/all</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Sign out everywhere</span>
  </summary>
  <div class="ep-body">
<p>Bumps the account's session version, which invalidates <b>every</b> cookie and Bearer token ever issued for it, on every device, including a copy someone walked off with. Passkeys are untouched; signing back in works immediately. Also clears the caller's own cookie. Unredeemed pairing codes for the account are voided too.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">All sessions revoked.<span class="r-sig"><a href="#schema-Ok">Ok</a> &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-accountDelete">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/delete</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Delete your own account and everything of yours</span>
  </summary>
  <div class="ep-body">
<p>The signed-in account removes itself for good, with the same clean-up as <code>/api/admin/user/delete</code>: the user record, their passkeys, their push subscriptions, their live presence, their training history file, their uploaded photos and videos (<code>DATA_DIR/uploads/&lt;uid&gt;/</code>) and any Coach credential stored for them. Not reversible. The body carries the account's name, typed back by its owner, and the same proof as setting a password (see OwnerProof): a passkey assertion made for this request, or the current password while <code>PASSWORD_LOGIN</code> is on. A paired phone (Bearer token) cannot hold a passkey for the server, so for a profile with no password that counts the pairing itself is the proof (audited as <code>device</code>; the app asks the phone's own screen lock first); a profile with one sends the current password from the phone too. Cookie sessions always need the proof. The name and the last-admin rule are checked before the proof is asked. The last admin is refused while any other profile remains (the instance would be left with nobody to run it); the only profile on an instance may delete itself. Clears the caller's cookie; every other session and Bearer token of the account stops working with it. Audited as <code>auth.account.delete</code>, with the name and the proof it was made with (<code>passkey</code>, <code>password</code>, <code>device</code>); a refused proof as <code>auth.proof.fail</code> with <code>act: account-delete</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p>
<pre><code>{
  &quot;name&quot;: &quot;Ada&quot;,
  &quot;current&quot;: &quot;correct horse battery staple&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The account and everything of theirs is gone.<span class="r-sig"><a href="#schema-Ok">Ok</a> &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>confirm-name</code>: the name is missing or is not this account's.<span class="r-sig"><code>{&quot;error&quot;:&quot;type the account name to confirm&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc"><code>last-admin</code>: the only admin, with other profiles still on the instance.<span class="r-sig"><code>{&quot;error&quot;:&quot;the last admin cannot leave while other profiles remain&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="pairing">
  <h2>Pairing</h2>
  <p class="sub">Mobile-app pairing (code from a signed-in browser tab)</p>
  <div class="eps">

<details class="ep" id="op-pairCreate">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/pair/create</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Mint a pairing code for the mobile app</span>
  </summary>
  <div class="ep-body">
<p>Called from an already signed-in browser tab (Settings → &quot;Pair the mobile app&quot;). Returns an 8-character code (alphabet without 0/O/1/I) the phone redeems within 5 minutes via /api/pair/redeem. One-shot. One live code per profile: minting a new one retires the previous one. Same proof as a device link (a passkey assertion made for this request, or the current password while password sign-in is on), since the phone token a code turns into is renewed for as long as it is used. Audited as <code>auth.pair.create</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">A fresh pairing code.<span class="r-sig">{ code: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pairRedeem">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/pair/redeem</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Redeem a pairing code for a Bearer token</span>
  </summary>
  <div class="ep-body">
<p>Called from the mobile app with the code shown in the browser. No session required: the code <i>is</i> the credential (one-shot, 5-minute TTL). Returns the same HMAC-signed session token the cookie would carry; the app sends it as <code>Authorization: Bearer &lt;token&gt;</code> from then on. CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">code<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The pairing code (case-insensitive).</span>
  </div>
</div>
<pre><code>{
  &quot;code&quot;: &quot;K7WQ2MZP&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Paired.<span class="r-sig">{ token: string, user: <a href="#schema-SessionUser">SessionUser</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Code unknown, already used, expired, or the account behind it is gone or disabled (deliberately the same message for all of these).<span class="r-sig"><code>{&quot;error&quot;:&quot;invalid or expired code&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="password">
  <h2>Password</h2>
  <p class="sub">Optional name-and-password sign-in (<code>PASSWORD_LOGIN=1</code>). Every route here is a 404 while the flag is off.</p>
  <div class="eps">

<details class="ep" id="op-loginPassword">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/login/password</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Sign in with a profile name or e-mail and a password</span>
  </summary>
  <div class="ep-body">
<p>Only a profile that has set a password can sign in this way. The identifier is the profile's display name or the e-mail address it added (<code>POST /api/account/email</code>), compared trimmed, NFKC-normalised and case-insensitively. Send it as <code>identifier</code> (what the app sends), <code>name</code> (the original field, still accepted) or <code>email</code>. In <code>identifier</code> and <code>name</code>, a value with an <code>@</code> is looked up as an e-mail first and then as a name; <code>email</code> is looked up only as an e-mail. A wrong password, an unknown name and a name whose profile has no password all get the same <code>401</code> after the same scrypt work, so neither the answer nor its timing says which names exist. So does a password that was right when its check started but was changed, reset or removed before the check finished. Five wrong passwords for an account are free and the sixth pauses it, whichever identifier they named it by (see <i>Throttling</i>); passkey sign-in is never paused by this. Sets the same session cookie as <code>/api/login/verify</code>. <b>Not</b> CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">identifier</span>
    <span class="p-type">string</span>
    <span class="p-desc">A profile name or an e-mail address.</span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc">The original field: a profile name, or an e-mail address.</span>
  </div>
  <div class="prow">
    <span class="p-name">email</span>
    <span class="p-type">string</span>
    <span class="p-desc">An e-mail address only.</span>
  </div>
  <div class="prow">
    <span class="p-name">password<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 256 chars)</span></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Signed in. The session cookie is set.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Name or password missing.<span class="r-sig"><code>{&quot;error&quot;:&quot;name and password required&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">Wrong name or password. Deliberately one answer for every cause.<span class="r-sig"><code>{&quot;error&quot;:&quot;wrong name or password&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The right password for a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;this account has been disabled&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-registerPassword">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/register/password</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Create a profile with a name and password</span>
  </summary>
  <div class="ep-body">
<p>For browsers that cannot make a passkey (plain http on a LAN address, some Firefox setups). Creates the profile and signs it in. The same invite rules as passkey registration apply: on an invite-only instance the code is checked first, checked again after hashing, and burned. The password must be 10–256 characters and not one of the passwords guessing scripts try first; no two profiles with a password may share a name. An optional <code>email</code> is stored as the profile's sign-in e-mail (see <code>POST /api/account/email</code>); one that is not an address is refused with <code>400 email-invalid</code>, one that is in use with <code>409 email-taken</code>. Both are asked only after the hash and the second invite check, so without a valid code it is never answered, which counts against the caller's address like a wrong invite code. <b>Not</b> CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">name<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">password<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 256 chars)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">code</span>
    <span class="p-type">string</span>
    <span class="p-desc">Invite code (INVITE_ONLY only).</span>
  </div>
  <div class="prow">
    <span class="p-name">email</span>
    <span class="p-type">string <span class="p-hint">(&le; 254 chars)</span></span>
    <span class="p-desc">Optional sign-in e-mail.</span>
  </div>
</div>
<pre><code>{
  &quot;name&quot;: &quot;Ada&quot;,
  &quot;password&quot;: &quot;correct horse battery staple&quot;,
  &quot;code&quot;: &quot;3F9C21A07B54D688&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Registered and signed in. The session cookie is set.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The password breaks the policy with <code>too-short</code> (under 10 characters), <code>too-long</code> (over 256) or <code>too-common</code>; a field is <code>missing</code>; or <code>email-invalid</code>: the <code>email</code> given is not an e-mail address.<span class="r-sig"><code>{&quot;error&quot;:&quot;this password is too easy to guess&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;that is not an e-mail address&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Invite-only and the code is missing, used or revoked.<span class="r-sig"><code>{&quot;error&quot;:&quot;a valid invite code is required&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc"><code>name-taken</code> (see NameTaken) or <code>email-taken</code>: the e-mail is in use by another profile.<span class="r-sig"><code>{&quot;error&quot;:&quot;another profile already uses this e-mail address&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-redeemPasswordReset">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/login/password-reset</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Set a new password with an admin's one-time reset code</span>
  </summary>
  <div class="ep-body">
<p>Redeems the code from <code>POST /api/admin/user/password-reset</code> (valid 24 h, single use, stored only as a hash; dashes, spaces and case do not matter) and signs in. A new password that breaks the policy is refused without using up the code. Every other session of the account ends. Wrong codes count against the caller's address only (see <i>Throttling</i>), never against the name, so they cannot keep a real code from working. The profile is named by its name or its sign-in e-mail, in <code>identifier</code>, <code>name</code> or <code>email</code> as at sign-in. <b>Not</b> CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">identifier</span>
    <span class="p-type">string</span>
    <span class="p-desc">The profile name or its sign-in e-mail.</span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc">The original field; an e-mail works here too.</span>
  </div>
  <div class="prow">
    <span class="p-name">email</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">code<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">next<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 256 chars)</span></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Password set and signed in. The session cookie is set.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>reset-invalid</code> (wrong, used or expired code; one answer for all), <code>missing</code>, or a password-policy code.<span class="r-sig"><code>{&quot;error&quot;:&quot;that reset code is wrong or has expired&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The account has been disabled.<span class="r-sig"><code>{&quot;error&quot;:&quot;this account has been disabled&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">Another profile already signs in with this name, or holds it with a reset code that has not been used or expired yet.<span class="r-sig"><code>{&quot;error&quot;:&quot;another profile already signs in with this name&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getAccountPassword">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/account/password</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Whether this profile has a password</span>
  </summary>
  <div class="ep-body">

    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The profile's password state.<span class="r-sig">{ set: boolean, setAt: string | null, passkeys: integer, name: string, nameTaken: boolean, email: string | null }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-setAccountPassword">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/password</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Set or change this profile's password</span>
  </summary>
  <div class="ep-body">
<p>Proof first: <code>current</code> when the profile has a password, or a passkey assertion made for this request (<code>cid</code> from <code>POST /api/login/options</code>, <code>credential</code> signed by one of <i>this</i> profile's passkeys). The passkey is the only way to set a first password, and the way to replace a forgotten one. A session alone is never enough. Wrong <code>current</code> values count toward the same pause as wrong sign-ins. On success the session version is bumped, which ends every other session and pending pairing code of the account; the caller's own continues on a fresh cookie, or a fresh <code>token</code> for a Bearer caller.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">next<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(&le; 256 chars)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">current</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">cid</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">credential</span>
    <span class="p-type"><a href="#schema-WebAuthnAuthenticationCredential">WebAuthnAuthenticationCredential</a></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Saved. Other sessions have ended.<span class="r-sig">{ ok: always true, token: string } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The new password breaks the policy (<code>too-short</code> under 10 characters, <code>too-long</code> over 256, or <code>too-common</code>), or a field is <code>missing</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;this password is too easy to guess&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof: <code>current-required</code>, <code>current-wrong</code>, <code>passkey-required</code> (no password yet, so a passkey has to confirm), or <code>passkey</code> (the assertion did not verify or belongs to another profile).<span class="r-sig"><code>{&quot;error&quot;:&quot;your current password is not right&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">Another profile already signs in with this name, or holds it with a reset code that has not been used or expired yet.<span class="r-sig"><code>{&quot;error&quot;:&quot;another profile already signs in with this name&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-removeAccountPassword">
  <summary>
    <span class="m delete">DELETE</span>
    <span class="ep-path"><code>/api/account/password</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Remove this profile's password</span>
  </summary>
  <div class="ep-body">
<p>Refused while the profile has no passkey: the password would be its last way in. Otherwise the body carries the same proof setting one takes: <code>current</code>, the password itself, or a passkey assertion made for this request (<code>cid</code> from <code>POST /api/login/options</code>, <code>credential</code> signed by one of <i>this</i> profile's passkeys). A session alone is never enough: a stolen cookie must not take away the owner's way in where passkeys do not work. The last-way-in refusal comes before the proof is checked, and is checked again after it. Wrong <code>current</code> values count toward the same pause as wrong sign-ins. Existing sessions are left alone (<code>POST /api/logout/all</code> ends them). A profile without a password gets 200 as well, with no proof asked. Audited as <code>auth.password.remove</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Removed (or there was none).<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The password is the profile's only way in.<span class="r-sig"><code>{&quot;error&quot;:&quot;the password is the only way into this profile&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-setAccountEmail">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/email</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Set, change or remove the e-mail this profile may sign in with</span>
  </summary>
  <div class="ep-body">
<p>An e-mail address to type at <code>POST /api/login/password</code> instead of the profile name. No mail is ever sent to it (there is no verification and no reset mail; resets stay the admin's one-time code), so it is only an identifier. Stored trimmed, NFKC-normalised and lower-cased; at most 254 characters; unique across every profile, and never another password-holding profile's name. An empty or null <code>email</code> removes it (as <code>DELETE</code> does).</p>
<p>The body carries the same proof as setting a password (see OwnerProof): a session alone is never enough. Saving the address the profile already has answers 200 with no proof asked. An address in use by another profile is refused only after the proof, with <code>409 email-taken</code>, and counts against the caller's address and account (20 free, then 30 s doubling to 15 min), so the answer never costs less than a passkey prompt or a password check, and runs out after a few tries. It says an address is in use somewhere on this instance, never by whom. Audited as <code>auth.email.set</code> / <code>auth.email.change</code> with the address masked (<code>a…@e…</code>).</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p>
<pre><code>{
  &quot;email&quot;: &quot;[email protected]&quot;,
  &quot;current&quot;: &quot;correct horse battery staple&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Saved (or removed).<span class="r-sig">{ ok: always true, email: string | null }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Not an e-mail address.<span class="r-sig"><code>{&quot;error&quot;:&quot;that is not an e-mail address&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">Another profile already uses this address.<span class="r-sig"><code>{&quot;error&quot;:&quot;another profile already uses this e-mail address&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-removeAccountEmail">
  <summary>
    <span class="m delete">DELETE</span>
    <span class="ep-path"><code>/api/account/email</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Remove the e-mail this profile may sign in with</span>
  </summary>
  <div class="ep-body">
<p>The profile then signs in by its name only. Takes the same proof as setting one (OwnerProof); a profile without an e-mail gets 200 with none asked. Audited as <code>auth.email.remove</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Removed (or there was none).<span class="r-sig">{ ok: always true, email: null }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="passkeys">
  <h2>Passkeys</h2>
  <p class="sub">More than one passkey on a profile: list, add, rename, remove, plus one-time device links, which let another device of the same person add a passkey of its own.</p>
  <div class="eps">

<details class="ep" id="op-listPasskeys">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/account/passkeys</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">This profile's passkeys</span>
  </summary>
  <div class="ep-body">
<p>Every passkey that signs this profile in, without key material. <code>created</code> and <code>lastUsed</code> are null for a passkey made before they were recorded.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The list, and what it allows.<span class="r-sig"><a href="#schema-PasskeyList">PasskeyList</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-removePasskey">
  <summary>
    <span class="m delete">DELETE</span>
    <span class="ep-path"><code>/api/account/passkeys</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Remove one passkey</span>
  </summary>
  <div class="ep-body">
<p>Refused while it is the profile's last way in: its only passkey, and no password that can sign in (a password counts only while <code>PASSWORD_LOGIN</code> is on). Otherwise the body carries the same proof adding one takes (<code>OwnerProof</code>): a session alone is never enough, since a stolen cookie could otherwise choose which of the owner's passkeys is left. Any of the profile's passkeys may confirm, the one being removed included. The 404 and 409 refusals come before the proof is checked, and the last-way-in rule is checked again after it. Audited as <code>auth.passkey.remove</code>. An unused device code of the profile is dropped too, so one made with the removed passkey cannot add another afterwards.</p>
<p>Sessions are not tied to the passkey that opened them, so a session it already opened carries on; <code>POST /api/logout/all</code> ends those.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>
<p class="ep-h">Query parameters</p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The passkey's <code>id</code> from the list (its WebAuthn credential id).</span>
  </div>
</div>
<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Removed. The list as it is now.<span class="r-sig">object</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No passkey of this profile has that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;passkey not found&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">It is the profile's last way in.<span class="r-sig"><code>{&quot;error&quot;:&quot;this passkey is the only way into this profile&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-addPasskeyOptions">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/passkeys/options</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Add a passkey (step 1): prove it is you, get creation options</span>
  </summary>
  <div class="ep-body">
<p>A session alone is never enough to add a way in that outlives &quot;sign out everywhere&quot;. The body carries the same proof <code>POST /api/account/password</code> takes: a passkey assertion made for this request (<code>cid</code> from <code>POST /api/login/options</code>, <code>credential</code> signed by one of <i>this</i> profile's passkeys), or <code>current</code>, the profile's password, only while <code>PASSWORD_LOGIN</code> is on. With it off, a password kept from before is not checked at all and the answer is <code>passkey-required</code>, so a password-only profile has to move onto a passkey while the flag is still on. Wrong passwords count toward the sign-in pause.</p>
<p>The options use the profile's own user handle and list its passkeys in <code>excludeCredentials</code>, so an authenticator that already holds one refuses. The challenge is good for 5 minutes, for this profile, and only while the session version is unchanged.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Ceremony options.<span class="r-sig">{ cid: string, options: <a href="#schema-WebAuthnRegistrationOptions">WebAuthnRegistrationOptions</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The profile already has the most passkeys it can have (20).<span class="r-sig"><code>{&quot;error&quot;:&quot;a profile can have at most 20 passkeys&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-addPasskeyVerify">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/passkeys/verify</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Add a passkey (step 2): store the new one</span>
  </summary>
  <div class="ep-body">
<p>Verifies the attestation against the challenge from step 1 and stores the passkey on this profile. Audited as <code>auth.passkey.add</code>, with the proof that allowed it.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">cid<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">credential<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-WebAuthnRegistrationCredential">WebAuthnRegistrationCredential</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc">A label of the owner's choosing (&quot;Work laptop&quot;).</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Added. The list as it is now.<span class="r-sig">object</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Challenge expired, replayed or made for another profile, or the attestation did not verify.<span class="r-sig"><code>{&quot;error&quot;:&quot;challenge expired, try again&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">Not signed in, including a session that was ended (&quot;sign out everywhere&quot;, a new password) after step 1.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc"><code>credential-exists</code> (that passkey is already registered) or <code>passkey-limit</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;credential already registered&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-renamePasskey">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/passkeys/rename</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Name one passkey</span>
  </summary>
  <div class="ep-body">
<p>An empty name clears it; the app then shows a numbered &quot;Passkey n&quot;.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Renamed. The list as it is now.<span class="r-sig">object</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No passkey of this profile has that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;passkey not found&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-createDeviceLink">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/account/device-link</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Make a one-time device link</span>
  </summary>
  <div class="ep-body">
<p>For adding another device of the same person: returns a code of 12 characters from the pairing alphabet (60 bits), which the app also shows as a QR code of <code>&lt;app&gt;?link=&lt;code&gt;</code>. The other device redeems it with <code>/api/device-link/*</code> by creating a passkey of its own. The code is shown once, stored only as a SHA-256, good for 10 minutes and for one passkey; a newer one replaces it, and signing out everywhere, a new password, an admin reset or a disable drop it. Same proof as adding a passkey. Audited as <code>auth.link.create</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body</p><p class="p-desc"><a href="#schema-OwnerProof">OwnerProof</a></p>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The code, once.<span class="r-sig">{ code: string, expires: number }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">No acceptable proof that the owner is here: <code>passkey-required</code> (no password that counts, because none is set or <code>PASSWORD_LOGIN</code> is off, so a passkey has to confirm), <code>passkey</code> (the assertion did not verify, belongs to another profile, or was made for another challenge, one handed out for another ceremony or one already used), <code>current-required</code> or <code>current-wrong</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;confirm with your passkey first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The profile already has the most passkeys it can have (20).<span class="r-sig"><code>{&quot;error&quot;:&quot;a profile can have at most 20 passkeys&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">Every password check slot and the short queue behind them are taken.<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is busy, try again in a moment&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-deviceLinkOptions">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/device-link/options</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Redeem a device link (step 1): check the code, get creation options</span>
  </summary>
  <div class="ep-body">
<p>Called on the other device, which has no session: the code is the credential. Returns creation options for the profile the code belongs to, and that profile's id and name. Does not use the code up, so a dismissed passkey prompt can be tried again. Wrong codes count toward a per-address pause of link redemption (see <i>Throttling</i>). <b>Not</b> CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">code<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">Case, spaces and dashes are ignored.</span>
  </div>
</div>
<pre><code>{
  &quot;code&quot;: &quot;K7WQ-2MZP-4HXA&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Ceremony options.<span class="r-sig">{ cid: string, options: <a href="#schema-WebAuthnRegistrationOptions">WebAuthnRegistrationOptions</a>, id: string, name: string, recovery: boolean }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The code is wrong, used, replaced or expired, or its profile is gone or disabled: one answer for all of them.<span class="r-sig"><code>{&quot;error&quot;:&quot;that code is wrong, used or expired&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The profile already has the most passkeys it can have (20).<span class="r-sig"><code>{&quot;error&quot;:&quot;a profile can have at most 20 passkeys&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-deviceLinkVerify">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/device-link/verify</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Redeem a device link (step 2): store the passkey and sign this device in</span>
  </summary>
  <div class="ep-body">
<p>Verifies the attestation against the challenge from step 1 (which must have been made for this very code), stores the passkey on the code's profile, burns the code and sets the session cookie; the passkey just made is what signs the device in. Of two requests racing with one code, one wins. Audited as <code>auth.link.ok</code> (a recovery code as <code>auth.recovery.ok</code>), and every refusal as <code>auth.link.fail</code>. A recovery code also works on a profile at the passkey limit: the passkey used longest ago is removed to make room. <b>Not</b> CSRF-exempt.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">code<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">cid<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">credential<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-WebAuthnRegistrationCredential">WebAuthnRegistrationCredential</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Added and signed in.<span class="r-sig">{ user: <a href="#schema-SessionUser">SessionUser</a> } &middot; sets <code>Set-Cookie</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>link-invalid</code> (see below), a challenge that expired or was made for another code, or an attestation that did not verify.<span class="r-sig"><code>{&quot;error&quot;:&quot;that code is wrong, used or expired&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc"><code>credential-exists</code> or <code>passkey-limit</code>.<span class="r-sig"><code>{&quot;error&quot;:&quot;credential already registered&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">Paused by the sign-in throttle (see <i>Throttling</i> in the description). The request was not looked at; try again after <code>Retry-After</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;too many attempts, try again later&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="data">
  <h2>Data</h2>
  <p class="sub">Per-user state sync (the whole app state as one JSON blob)</p>
  <div class="eps">

<details class="ep" id="op-getData">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/data</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Pull the account's app state</span>
  </summary>
  <div class="ep-body">
<p>Returns the caller's entire app state as one JSON blob, or <code>{&quot;state&quot;: null}</code> if nothing has been synced yet, together with <code>rev</code>, the server's revision of that document (0 when there is none). A client keeps the <code>rev</code> it last read or wrote and sends it back as <code>baseRev</code> on the next push, which lets the server refuse a write over a document the client never saw (see the 409 on PUT).</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The stored state, or null, and its revision.<span class="r-sig">{ state: <a href="#schema-State">State</a> | null, rev: integer }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-putData">
  <summary>
    <span class="m put">PUT</span>
    <span class="ep-path"><code>/api/data</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Push the account's app state</span>
  </summary>
  <div class="ep-body">
<p>Replaces the stored state wholesale (atomic write; there is no merge on the server). The <code>active</code> field (an in-progress workout) is stripped before saving: a running session belongs to the device running it. Body limit 5 MiB.</p>
<p>With <code>baseRev</code> the write is conditional: it goes through only when <code>baseRev</code> equals the document's current revision, and answers 409 with the current document otherwise; the client merges the two and pushes again with the revision it was given. Without <code>baseRev</code> the write is unconditional (clients from before revisions, and deliberate replaces such as a backup import). The server stamps the new revision into the document as <code>_rev</code>; a <code>_rev</code> sent by the client is ignored.</p>
<p>The records of removals (<code>deleted</code>) and of edits (<code>edited</code>) never shrink: the stored ones are joined into the write (a reset keeps its own). A writer that does not stamp its own changes (no <code>stamped: true</code>; an API script, an older app) and sends the current <code>baseRev</code> gets them stamped by the server, at the server's time: every entry it removed (a workout, routine, custom exercise, weigh-in, card, profile or favourite), every setting and plan day it changed (<code>queue</code>, <code>week.&lt;day&gt;</code>, …), and every entry it edited (<code>_ts</code>, per field <code>_f</code>). That keeps a planner's new week, or a routine it removed, from being undone by a phone that reconnects later with an older change. A setting, plan day or entry field whose stored stamp (<code>edited</code>, <code>_f</code>) is later than the one the writer sends back keeps the stored value: the writer never saw that change, so send back the <code>edited</code> and <code>_f</code> you read. A writer that sends no <code>edited</code> at all is not held to it. An entry the document holds while a removal on record says it was deleted after its last edit is kept and marked as added back.</p>
<p>Such a writer also cannot delete what it does not know: a field of the stored document, of a stored routine, workout, custom exercise, card or profile, of a routine's exercise, or of a logged exercise or set that its copy leaves out comes back from the stored copy (an older app rebuilds an exercise from the fields it knows, which dropped pyramid sets made on an updated device). Only the fields v1.3.9 itself removes (a superset link, a note, a cleared set value, …) can be removed this way. Send <code>stamped: true</code> to remove anything else.</p>
<p>Every accepted write also starts the grace period of each stored file (tag <code>media</code>) the new state no longer references, and stops it for each one it references again. That bookkeeping never changes the answer.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">state<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-State">State</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">baseRev</span>
    <span class="p-type">integer | null</span>
    <span class="p-desc">The revision this client last read or wrote. Omit or null for an unconditional overwrite.</span>
  </div>
  <div class="prow">
    <span class="p-name">baseWid</span>
    <span class="p-type">string</span>
    <span class="p-desc">The write id (<code>_wid</code>) of the document this client last read or wrote. With <code>baseRev</code>, a write over a different document at the same revision (the data directory went back in time and the number was reached again) answers 409.</span>
  </div>
  <div class="prow">
    <span class="p-name">stamped</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">True when the client stamps its own changes in <code>deleted</code>, <code>edited</code> and each entry's <code>_ts</code>/<code>_f</code>, as the app does. Omit it to have the server stamp what changed against the stored document.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Saved.<span class="r-sig">{ ok: always true, ts: number | null, rev: integer, wid: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>state</code> missing or not an object, <code>state</code> an array or an object with nothing of the profile in it (<code>_rev</code>/<code>_ts</code> do not count; both would empty the profile), or <code>workouts</code>/<code>routines</code> set to anything other than an array or null. Entries inside those two arrays that are not objects (<code>null</code>, numbers, nested arrays) are dropped before the write rather than refused, so a client with a damaged copy still syncs.<span class="r-sig"><code>{&quot;error&quot;:&quot;state required&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;invalid state&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc"><code>baseRev</code> is not the current revision: another client wrote since this one last read. Carries the current document so the client can merge and retry.</span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-undefined">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/data/rev</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Current revision of the caller's profile state</span>
  </summary>
  <div class="ep-body">
<p>The <code>rev</code> that <code>GET /api/data</code> would return, without the document. Signed-in clients poll this while open and on every return to the foreground and fetch the document only when the number changed.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The current revision (0 when the profile has no state yet).<span class="r-sig">{ rev: integer, wid: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-nudgeCheck">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/nudge-check</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Whether a day was trained or excused (the phone's background check)</span>
  </summary>
  <div class="ep-body">
<p>Asked by the phone app in the background before a missed-day nudge or a workout-day reminder it scheduled on itself fires, so a day trained on another device is not nudged. A few bytes instead of the whole document: <code>done</code> is true when a workout is dated that day or the day carries a note; <code>nudge</code> is whether the server's copy of the nudge rule would still nudge that day (false once it is done, or when the plan has no session for it); <code>rev</code> is the profile's revision. Nothing of the workouts themselves.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>
<p class="ep-h">Query parameters</p><div class="ptab">
  <div class="prow">
    <span class="p-name">date<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(date)</span></span>
    <span class="p-desc">The day, YYYY-MM-DD, in the phone's own calendar.</span>
  </div>
</div>

    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">How that day stands.<span class="r-sig">{ date: string <span class="p-hint">(date)</span>, done: boolean, nudge: boolean, rev: integer }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>date-invalid</code>: not a YYYY-MM-DD date.<span class="r-sig"><code>{&quot;error&quot;:&quot;date must be YYYY-MM-DD&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="push">
  <h2>Push</h2>
  <p class="sub">Web Push (VAPID) subscriptions, rest-timer and test pushes</p>
  <div class="eps">

<details class="ep" id="op-pushPublicKey">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/push/public-key</code><span class="ep-chip public">public</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">VAPID public key</span>
  </summary>
  <div class="ep-body">
<p>The instance's Web-Push application server key (generated once at first boot), for <code>PushManager.subscribe({applicationServerKey})</code>. Public.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Public: no authentication required.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The key.<span class="r-sig">{ key: string }</span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushSubscribe">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/push/subscribe</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Register a Web-Push subscription</span>
  </summary>
  <div class="ep-body">
<p>Stores the browser's <code>PushSubscription</code> for this account. Only <code>endpoint</code> and the two protocol keys are kept. The endpoint must be a public <code>https://</code> URL; private/loopback/link-local addresses are refused (here and again at send time, against DNS rebinding). At most 20 subscriptions per user; the oldest are dropped first. Re-subscribing an existing endpoint replaces it and keeps its original <code>created</code>. The client re-sends its subscription on every signed-in boot, so a row the instance lost comes back on its own. An endpoint stored for another account moves to the caller only when the request carries that subscription's own keys (the same browser, signed into another account); otherwise it is a 409 and the row stays where it was.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">subscription<em class="p-req" title="required">required</em></span>
    <span class="p-type"><a href="#schema-PushSubscription">PushSubscription</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">deviceId</span>
    <span class="p-type">string</span>
    <span class="p-desc">A token the browser made up for itself (stored in its localStorage), so rest-timer pushes can be aimed at the device that started the rest. Optional; anything that is not a short token is ignored, and a re-send of an endpoint without one keeps the id its row already has.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Stored.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Malformed subscription, or an endpoint that isn't acceptable.<span class="r-sig"><code>{&quot;error&quot;:&quot;invalid subscription&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;endpoint must not point at a private address&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The endpoint is stored for another account and the request does not carry that subscription's keys.<span class="r-sig"><code>{&quot;error&quot;:&quot;this subscription belongs to another account&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushStatus">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/push/status</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Does the server hold this subscription?</span>
  </summary>
  <div class="ep-body">
<p>Whether the caller's account has a stored subscription with exactly this <code>endpoint</code>. The browser's <code>PushManager.getSubscription()</code> says nothing about the server's side: a row pruned after a dead send (404/410/403) leaves the browser subscribed to nowhere. So the client asks here before showing the notifications switch as on, and re-registers when the answer is no. A stored subscription also names the <code>deviceId</code> it is stored with, and the client re-registers when that is not its own: a row stored without one (from before device ids) sends that device's rest-timer alerts to every subscription of the account.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>
<p class="ep-h">Query parameters</p><div class="ptab">
  <div class="prow">
    <span class="p-name">endpoint<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(uri)</span></span>
    <span class="p-desc"></span>
  </div>
</div>

    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The answer.<span class="r-sig">{ subscribed: boolean, deviceId: string | null }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushUnsubscribe">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/push/unsubscribe</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Remove a Web-Push subscription</span>
  </summary>
  <div class="ep-body">
<p>Removes the caller's subscription with the given endpoint. Idempotent.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">endpoint<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(uri)</span></span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Removed (or was never there).<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushTest">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/push/test</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Send a test notification</span>
  </summary>
  <div class="ep-body">
<p>Sends a test push to all of the caller's subscriptions (localized with the <code>lang</code> in their synced state). Returns 200 even if delivery to individual endpoints fails; dead endpoints (404/410, and 403 for a subscription made against a VAPID key the instance no longer has) are pruned as a side effect.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Sends attempted.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushRestTimer">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/push/rest-timer</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Schedule a server-side rest-timer push</span>
  </summary>
  <div class="ep-body">
<p>Schedules one push after <code>seconds</code> (a number or numeric string ≥ 1, clamped to 3600). One pending timer per device, keyed by <code>deviceId</code>, the same token the subscription was registered with; a new call from the same device replaces it, and the push goes only to that device's subscriptions. Without a <code>deviceId</code> there is one timer per account and the push goes to every subscription, as before. The client schedules this on rest start/extend and cancels on skip or on-screen completion. The push only actually fires when the tab was backgrounded/suspended and never got to cancel it. Timers live in memory: an API restart drops them.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">seconds<em class="p-req" title="required">required</em></span>
    <span class="p-type">number <span class="p-hint">(1&ndash;3600)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">deviceId</span>
    <span class="p-type">string</span>
    <span class="p-desc">The browser's own token, see <code>POST /api/push/subscribe</code>. Optional.</span>
  </div>
</div>
<pre><code>{
  &quot;seconds&quot;: 90,
  &quot;deviceId&quot;: &quot;3f9c1d2e7b0a4c6d9e8f1a2b3c4d5e6f&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Timer scheduled.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>seconds</code> missing, not numeric, or below 1. Nothing is scheduled.<span class="r-sig"><code>{&quot;error&quot;:&quot;seconds required&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-pushRestTimerCancel">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/push/rest-timer/cancel</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Cancel the pending rest-timer push</span>
  </summary>
  <div class="ep-body">
<p>Cancels the caller's scheduled rest-timer push, if any. With a <code>deviceId</code> only that device's timer; without one, every pending timer of the account. Idempotent.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">deviceId</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Cancelled (or nothing was pending).<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="activity">
  <h2>Activity</h2>
  <p class="sub">Live-workout presence heartbeat</p>
  <div class="eps">

<details class="ep" id="op-postActivity">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/activity</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Live-workout presence heartbeat</span>
  </summary>
  <div class="ep-body">
<p>The client pings this every ~20 s while a workout is on screen; the admin dashboard reads who is training right now. Purely ephemeral, in-memory, never persisted; entries expire 70 s after the last ping. <code>{&quot;active&quot;: false}</code> is the &quot;left&quot; signal: with <code>reason</code> <code>navigated</code> or <code>closed</code>, or with no reason, it drops the caller's entry immediately. With <code>reason: hidden</code> (the page went to the background) it marks the entry away instead, and the entry stops being listed 45 s after that mark unless a heartbeat arrives first; a heartbeat clears the mark. The 70 s expiry applies either way.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">active</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">false ends the presence (see <code>reason</code>); true (with the fields below) updates it.</span>
  </div>
  <div class="prow">
    <span class="p-name">reason</span>
    <span class="p-type">&quot;navigated&quot; | &quot;closed&quot; | &quot;hidden&quot;</span>
    <span class="p-desc">Why the client sent <code>active: false</code>: <code>navigated</code> (an in-app route change), <code>closed</code> (the page is going away) or <code>hidden</code> (the page went to the background). <code>navigated</code> and <code>closed</code> drop the entry at once, as no reason does; <code>hidden</code> marks it away rather than dropping it. Ignored with <code>active: true</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string <span class="p-hint">(&le; 60 chars)</span></span>
    <span class="p-desc">Routine/workout name being trained.</span>
  </div>
  <div class="prow">
    <span class="p-name">exIdx</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Current exercise index (0-based).</span>
  </div>
  <div class="prow">
    <span class="p-name">exTotal</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Exercises in the workout.</span>
  </div>
  <div class="prow">
    <span class="p-name">setsDone</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">setsTotal</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">startedAt</span>
    <span class="p-type">number</span>
    <span class="p-desc">Workout start, ms since epoch (defaults to now).</span>
  </div>
</div>
<pre><code>{
  &quot;active&quot;: true,
  &quot;name&quot;: &quot;Push Day&quot;,
  &quot;exIdx&quot;: 2,
  &quot;exTotal&quot;: 5,
  &quot;setsDone&quot;: 7,
  &quot;setsTotal&quot;: 16,
  &quot;startedAt&quot;: 1756500000000
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Presence updated.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="media">
  <h2>Media</h2>
  <p class="sub">The photo, GIF or video of a user's own custom exercise, and the photos and videos attached to a logged workout. Stored per profile (one quota for both) and named by the SHA-256 of its bytes; the state only carries a <code>MediaRef</code>. Every route here is a 404 when the instance runs with <code>MEDIA_UPLOADS=0</code>.</p>
  <div class="eps">

<details class="ep" id="op-getMedia">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/media/{hash}</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Download one of your photos or videos</span>
  </summary>
  <div class="ep-body">
<p>The stored file, whole, from the caller's own folder only: another profile's file answers exactly like one that was never uploaded (404). The body is the file, not JSON, with headers that keep a browser from ever treating it as a page: <code>Content-Type</code> from the sniffed type (never <code>text/*</code> or SVG), <code>X-Content-Type-Options: nosniff</code>, <code>Content-Security-Policy: default-src 'none'; sandbox</code>, <code>Cross-Origin-Resource-Policy: same-origin</code>, <code>Content-Disposition: inline</code>, <code>X-Robots-Tag: noindex</code> and <code>Cache-Control: private, no-store</code>. The app keeps its own verified copy, and an HTTP-cache copy would outlive signing out.</p>
<p>No <code>Range</code> and no <code>ETag</code>: the app downloads a file once, checks it against its hash and keeps it. A paired phone fetches with its bearer token; <code>&lt;img src&gt;</code> cannot carry one. Not throttled.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The file.<span class="r-sig">sets <code>Content-Length</code>, <code>Content-Disposition</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">Not in the caller's folder. Never uploaded, removed by the sweep, or someone else's.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such file&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-putMedia">
  <summary>
    <span class="m put">PUT</span>
    <span class="ep-path"><code>/api/media/{hash}</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Upload one photo, GIF or video</span>
  </summary>
  <div class="ep-body">
<p>The body is the raw file; <code>Content-Type</code> must be one of the seven types below and <code>Content-Length</code> is optional (chunked uploads are capped while they stream). The path names the SHA-256 of the bytes, and the file is stored only if they hash to it. Idempotent: uploading a file the server already has answers 200 with <code>existed: true</code>.</p>
<p>What is stored is decided by the file's first bytes, not by the declared type. The declared type only has to be in the same category, a still (JPEG, PNG, WebP, GIF) or a video (MP4, MOV, WebM): a JPEG declared as a GIF is stored as the JPEG it is, a video declared as an image is refused. The cap of the kind the bytes turned out to be applies (<code>MEDIA_IMAGE_MAX_MB</code>, <code>MEDIA_GIF_MAX_MB</code>, <code>MEDIA_VIDEO_MAX_MB</code>), and an MP4 or MOV must be a well-formed file no longer than <code>MEDIA_VIDEO_MAX_SEC</code> (+1 s), read from its headers. HEIC/AVIF, SVG, HTML and every other type are refused; the app converts HEIC photos before uploading. The server never decodes or alters a file: the app has already re-encoded photos and removed video metadata on the device.</p>
<p>Checked in this order: session (401), the hourly budget and at most two uploads at once per profile (429), the declared type (415), a declared length over the cap (413 before a byte is read), already stored (200), the quota (413 <code>media-quota</code>; files the profile already dropped get one hour instead of the grace to make room), free disk (507), then while and after streaming: size (413), hash (400), sniffed type (415), sniffed cap (413), video checks (415/413). No bytes for 60 s ends the upload with 408. A refused upload is read and discarded up to twice its cap, so the answer reaches the client.</p>
<p>A new file that the profile's state does not reference yet starts its grace period at once, so a state push that never comes does not keep it forever.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The server already had these bytes (from this or another of your devices).<span class="r-sig"><a href="#schema-MediaStored">MediaStored</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s2">201</span>
    <span class="p-desc">Stored.<span class="r-sig"><a href="#schema-MediaStored">MediaStored</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The bytes do not hash to the name in the path (<code>hash-mismatch</code>).<span class="r-sig"><code>{&quot;error&quot;:&quot;the file does not match its name&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">A browser request from another origin (see <i>CSRF</i>).<span class="r-sig"><code>{&quot;error&quot;:&quot;cross-origin request refused&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">408</span>
    <span class="p-desc">No bytes arrived for 60 seconds (<code>timeout</code>). The connection is closed.<span class="r-sig"><code>{&quot;error&quot;:&quot;the upload stalled&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">413</span>
    <span class="p-desc">- <code>media-too-large</code>: over the cap of its kind; <code>maxMB</code> says the cap. - <code>media-quota</code>: the profile's space is full; <code>usedMB</code> and <code>quotaMB</code> say how full. - <code>media-too-long</code>: a video longer than <code>maxSec</code> seconds.<span class="r-sig"><code>{&quot;error&quot;:&quot;that file is too large&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;your space for photos and videos is full&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;that video is too long&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">415</span>
    <span class="p-desc"><code>media-type</code>: the declared type is not one of the seven, the bytes are none of them, or they are a video declared as an image (or the reverse). <code>media-invalid</code>: an MP4 or MOV whose boxes do not add up.<span class="r-sig"><code>{&quot;error&quot;:&quot;that file type is not accepted&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;that video could not be read&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc"><code>locked</code>: more than <code>MEDIA_UPLOADS_PER_HOUR</code> uploads this hour; <code>busy</code>: two uploads of this profile are already in flight (<code>retryAfter</code> 5).<span class="r-sig"><code>{&quot;error&quot;:&quot;too many uploads, try again later&quot;}</code> &middot; <code>{&quot;error&quot;:&quot;too many uploads at once, try again in a moment&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">507</span>
    <span class="p-desc">The server's disk has less than <code>MEDIA_MIN_FREE_MB</code> free (<code>storage-full</code>).<span class="r-sig"><code>{&quot;error&quot;:&quot;the server is running out of disk space&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-mediaMissing">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/media/missing</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Which of these files the server does not have</span>
  </summary>
  <div class="ep-body">
<p>The app sends every hash its state references and uploads only what comes back, so the same call moves a guest's files into a new account, a phone's into its pairing, a backup's into the server, and re-sends a file the sweep removed while a device still had it. Answered from the caller's own folder only.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">hashes<em class="p-req" title="required">required</em></span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The subset the server does not have, in the order sent, and the profile's usage.<span class="r-sig">{ missing: string[], usage: <a href="#schema-MediaUsage">MediaUsage</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc"><code>hashes</code> is missing, not a list, longer than 1000, or holds something that is not a lowercase SHA-256 (<code>bad-request</code>).</span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">A browser request from another origin (see <i>CSRF</i>).<span class="r-sig"><code>{&quot;error&quot;:&quot;cross-origin request refused&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-mediaSweep">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/media/sweep</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Delete every file your current state does not reference</span>
  </summary>
  <div class="ep-body">
<p>What &quot;Reset everything&quot; does after pushing the empty state: every stored file of the caller that the stored state does not reference goes now, without the grace period. A state that cannot be read removes nothing. At most 10 an hour per profile (429 <code>locked</code>). Recorded in the activity log as <code>media.sweep</code>.</p>
<p>Without this call nothing is lost either: the hourly sweep removes a file once the state has not referenced it for <code>MEDIA_GC_GRACE_DAYS</code> days (14), and only for profiles whose state reads. A missing or unreadable state, or a profile missing from <code>db.json</code>, never deletes anything.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p>
<pre><code>{}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">What was removed, and what is left.<span class="r-sig">{ removed: integer, freedBytes: integer, usage: <a href="#schema-MediaUsage">MediaUsage</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">A browser request from another origin (see <i>CSRF</i>).<span class="r-sig"><code>{&quot;error&quot;:&quot;cross-origin request refused&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">More than 10 sweeps this hour (<code>locked</code>).<span class="r-sig"><code>{&quot;error&quot;:&quot;too many uploads, try again later&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="coach">
  <h2>AI Coach</h2>
  <p class="sub">AI Coach: plans, reviews and debriefs. Every route here answers 503 unless the instance has the Coach switched on and a provider connected.</p>
  <div class="eps">

<details class="ep" id="op-getCoachDisclosure">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/coach/disclosure</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">What the consent screen must say</span>
  </summary>
  <div class="ep-body">
<p>The categories of data a Coach job would send, and the provider it would go to, read straight from the module that builds the payload, so the consent screen cannot drift from what actually leaves the box.</p>
<p>Needs a session but <i>not</i> a connected Coach: the screen that collects consent runs before there is anything to consent to.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The disclosure.<span class="r-sig">{ provider: string, providerLabel: string, host: string, categories: (&quot;plan&quot; | &quot;training&quot; | &quot;bodyweight&quot; | &quot;profile&quot; | &quot;prefs&quot;)[], version: integer }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getCoachStatus">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/coach/status</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The running job, the waiting proposal and today's budget</span>
  </summary>
  <div class="ep-body">
<p>What the Coach screen polls. Also the only place a proposal past its 14-day expiry is retired. A phone that stays closed never polls, so nothing else would notice.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">This profile's Coach state.<span class="r-sig"><a href="#schema-CoachStatus">CoachStatus</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachPlan">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/plan</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Ask for a training plan</span>
  </summary>
  <div class="ep-body">
<p>Queues a <code>create</code> job. With <code>intake</code> it builds a plan from the answers given on the intake screen; with <code>refine</code> it reworks the proposal already waiting, in the words of the person reading it. The answer is 202 and a job id; the result arrives through <code>GET /api/coach/status</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">intake</span>
    <span class="p-type"><a href="#schema-CoachIntake">CoachIntake</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">refine</span>
    <span class="p-type">string <span class="p-hint">(&le; 4000 chars)</span></span>
    <span class="p-desc">A change asked for in plain words, applied to the proposal now waiting. Cut to the instance's <code>maxMessageLen</code> (1000 unless the admin changed it; 200–4000).</span>
  </div>
  <div class="prow">
    <span class="p-name">lang</span>
    <span class="p-type">string</span>
    <span class="p-desc">The language the app is showing, which the Coach writes in. Absent or not a language tag, the profile's stored <code>lang</code> is used.</span>
  </div>
</div>
<pre><code>{
  &quot;intake&quot;: {
    &quot;goal&quot;: &quot;muscle&quot;,
    &quot;experience&quot;: &quot;novice&quot;,
    &quot;daysPerWeek&quot;: 3,
    &quot;equipment&quot;: [
      &quot;dumbbell&quot;,
      &quot;barbell&quot;
    ]
  }
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">202</span>
    <span class="p-desc">Queued. The job runs in the background; its outcome arrives through <code>GET /api/coach/status</code>, which the client polls.<span class="r-sig">{ job: object }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachReview">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/review</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Ask for a review of the training since the last one</span>
  </summary>
  <div class="ep-body">
<p>Queues a <code>review</code> job, the same job the weekly cadence queues on its own. The answer is either a change-set to accept or reject, or &quot;nothing to change&quot; with the reason, both delivered through <code>GET /api/coach/status</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">note</span>
    <span class="p-type">string <span class="p-hint">(&le; 4000 chars)</span></span>
    <span class="p-desc">Anything the profile wants the Coach to know this time round. Cut to the instance's <code>maxMessageLen</code> (1000 unless the admin changed it; 200–4000).</span>
  </div>
  <div class="prow">
    <span class="p-name">lang</span>
    <span class="p-type">string</span>
    <span class="p-desc">The language the app is showing, which the Coach writes in. Absent or not a language tag, the profile's stored <code>lang</code> is used.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">202</span>
    <span class="p-desc">Queued. The job runs in the background; its outcome arrives through <code>GET /api/coach/status</code>, which the client polls.<span class="r-sig">{ job: object }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachAsk">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/ask</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Ask the Coach a question</span>
  </summary>
  <div class="ep-body">
<p>Queues an <code>ask</code> job: a question from the chat, answered in plain text. It changes nothing; the answer arrives as a pending proposal of kind <code>ask</code> with an <code>answer</code> string, which the client writes into the chat and resolves. The running session, which the server never holds, may ride along as <code>today</code>; the payload builder bounds it like a logged workout.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">text<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The question. Cut at the instance's message length.</span>
  </div>
  <div class="prow">
    <span class="p-name">today</span>
    <span class="p-type">object</span>
    <span class="p-desc">The session running on the device (<code>entries</code> with their sets), or absent.</span>
  </div>
  <div class="prow">
    <span class="p-name">lang</span>
    <span class="p-type">string</span>
    <span class="p-desc">The language the app is showing, which the Coach answers in.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">202</span>
    <span class="p-desc">Queued. The job runs in the background; its outcome arrives through <code>GET /api/coach/status</code>, which the client polls.<span class="r-sig">{ job: object }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">No question in the body (<code>code</code> is <code>invalid</code>).</span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachDebrief">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/debrief</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Ask for a read of one session</span>
  </summary>
  <div class="ep-body">
<p>Queues a <code>debrief</code> job: one workout, read closely. It changes nothing; the card it produces is kept in the profile's log. With no <code>workoutId</code> the most recent session is read.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">workoutId</span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span> | null</span>
    <span class="p-desc">The workout to read; null or absent means the latest.</span>
  </div>
  <div class="prow">
    <span class="p-name">lang</span>
    <span class="p-type">string</span>
    <span class="p-desc">The language the app is showing, which the Coach writes in. Absent or not a language tag, the profile's stored <code>lang</code> is used.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">202</span>
    <span class="p-desc">Queued. The job runs in the background; its outcome arrives through <code>GET /api/coach/status</code>, which the client polls.<span class="r-sig">{ job: object }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">429</span>
    <span class="p-desc">The Coach will not take this job, and says which reason in <code>code</code>: - <code>busy</code> (409): a job for this profile is already running. - <code>shared</code> (409): instance mode, and the credential belongs to another profile. - <code>cap</code> (429): this profile's or the instance's daily limit is spent. - <code>consent</code> (403): no consent recorded for this profile. - <code>unprivileged</code> (503): the privilege drop cannot be performed, so no job runs. The message is the one to show; the raw provider detail never reaches the user.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is already thinking about your training&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachResolve">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/pending/resolve</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Apply or discard the waiting proposal</span>
  </summary>
  <div class="ep-body">
<p>The client applies the accepted changes to its own state and syncs them through <code>PUT /api/data</code>; this only records the decision and clears the proposal. Sending it when nothing is waiting is a no-op, not an error.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">accepted</span>
    <span class="p-type">string[]</span>
    <span class="p-desc">Ids of the changes the person kept.</span>
  </div>
  <div class="prow">
    <span class="p-name">rejected</span>
    <span class="p-type">string[]</span>
    <span class="p-desc">Ids of the changes they turned down.</span>
  </div>
  <div class="prow">
    <span class="p-name">dismissed</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">True when the whole proposal was thrown away unread.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Recorded; the proposal is cleared.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getCoachCohort">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/coach/cohort</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">How this profile sits against the others who opted in</span>
  </summary>
  <div class="ep-body">
<p>Medians only, and only when at least three profiles on the instance share. Nothing at all for a profile that does not share itself, or on an instance where the admin has not switched the comparison on. Each of those is a 200 saying which it is.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The comparison, or the reason there isn't one.<span class="r-sig"><a href="#schema-CoachCohort">CoachCohort</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachCohortShare">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/cohort/share</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Opt this profile in or out of the comparison</span>
  </summary>
  <div class="ep-body">
<p>Held server-side rather than in the synced state: this flag decides whether the profile's numbers reach other people, and a stale device syncing an older copy must not be able to turn it back on.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">share</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
</div>
<pre><code>{
  &quot;share&quot;: true
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The flag as it now stands.<span class="r-sig">{ ok: always true, sharing: boolean }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s5">503</span>
    <span class="p-desc">The Coach is not set up on this instance (switched off, or no provider connected). Every Coach route answers this rather than pretending, so an unconfigured instance renders exactly the app it was before the feature existed. <code>code</code> is <code>off</code>, the class a job refused at enqueue for the same reason carries; the app shows its own line for it.<span class="r-sig"><code>{&quot;error&quot;:&quot;the Coach is not set up on this instance&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getCoachAccount">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/coach/account</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Whose provider account this profile would spend</span>
  </summary>
  <div class="ep-body">
<p>Its own route because both the Coach screen and the admin card have to state it, and neither should be inferring it from settings. In instance mode a personal credential binds to the first profile that spends it; every other profile is refused outright rather than warned, and <code>reason</code> says so.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The account this profile's jobs would run on.<span class="r-sig">{ mode: &quot;instance&quot; | &quot;profile&quot;, provider: string, providerLabel: string, account: string | null, connected: boolean, reason: string | null, message: string | null }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postCoachForget">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/coach/forget</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Drop everything the server holds for this profile</span>
  </summary>
  <div class="ep-body">
<p>Consent withdrawn, or the Coach switched off for this profile: the job record, the waiting proposal, the history and the sharing flag go at once, without waiting for a sync to carry the news. A job already running is cancelled where the adapter allows it and writes nothing back either way.</p>
<p>Today's job count is the one thing that survives. It is the spending record the daily cap reads, and forgetting must not hand out a fresh cap.</p>
<p>Needs a session only: a profile must be able to be forgotten on an instance whose Coach has since been switched off.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session: the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Forgotten.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

<section class="api-sec" id="admin">
  <h2>Admin</h2>
  <p class="sub">Admin dashboard. Requires an admin session (<code>ADMIN_UIDS</code> or <code>admin:true</code>)</p>
  <div class="eps">

<details class="ep" id="op-adminRecoveryCode">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/user/recovery</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Make a one-time recovery code (#584)</span>
  </summary>
  <div class="ep-body">
<p>For someone who lost every way in, on any instance (with or without <code>PASSWORD_LOGIN</code>). Returns a code (12 characters from the pairing alphabet, 60 bits), shown once, stored only as a SHA-256, valid for 24 h. The person redeems it like a device link (<code>POST /api/device-link/options</code> and <code>/verify</code>): the device they use gets a new passkey for the profile and is signed in. Making it bumps the profile's session version (every session, pending pairing code and device link ends); passkeys and the password stay. A newer code replaces an older one.</p>
<p>Any admin may make one for a profile that is not an admin; only the owner for an admin; nobody for the owner (403 <code>owner</code>: the owner uses the server command <code>node recover.js &lt;name&gt;</code>), for oneself (400 <code>self</code>) or for a disabled profile (400 <code>disabled</code>). Audited as <code>admin.recovery.create</code>; a refusal for an admin as <code>admin.denied</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The code, once.<span class="r-sig">{ ok: always true, name: string, code: string, expires: number }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Oneself, or a disabled profile.<span class="r-sig"><code>{&quot;error&quot;:&quot;enable the account first&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Not an admin; an admin who is not the owner asking for an admin; or the target is the owner.<span class="r-sig"><code>{&quot;error&quot;:&quot;the owner recovers with the server command (recover.js)&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such user&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminPasswordReset">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/user/password-reset</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Issue a one-time password reset code</span>
  </summary>
  <div class="ep-body">
<p>Returns a code (12 characters from the pairing alphabet, 60 bits) that is shown once, stored only as a SHA-256, valid for 24 h and good for one <code>POST /api/login/password-reset</code>. Issuing it removes the profile's current password and bumps its session version (every session and pending pairing code ends); passkeys keep working. A newer code replaces an older one. Admin accounts are refused; an admin sets their own password in Settings. Audited as <code>admin.password.reset</code>.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The code, once.<span class="r-sig">{ ok: always true, name: string, code: string, expires: number }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The target is an admin.<span class="r-sig"><code>{&quot;error&quot;:&quot;an admin sets their own password in Settings&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such user&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">409</span>
    <span class="p-desc">Another profile already signs in with this name, or holds it with a reset code that has not been used or expired yet.<span class="r-sig"><code>{&quot;error&quot;:&quot;another profile already signs in with this name&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminUsers">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/admin/users</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">List all users</span>
  </summary>
  <div class="ep-body">
<p>One row per user with workout counts, last sync, push status and live presence. <code>workouts</code> counts only the entries the drill-down can show. Admin only.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">All users.<span class="r-sig">{ users: <a href="#schema-AdminUserRow">AdminUserRow</a>[], invite_only: boolean, password_login: boolean, now: number }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminUser">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/admin/user</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">One user in detail</span>
  </summary>
  <div class="ep-body">
<p>Drill-down: full workout history (newest first) and body-weight log for one user. Admin only. Anything in <code>routines</code>, <code>bodyweight</code> or <code>workouts</code> that is not an object is left out, and a list that is not an array reads as empty: PUT /api/data drops those entries now, but a state file written before it did still has them and this route has to answer for it. A workout's <code>media</code> (its photos and videos) is left out: they are the owner's own.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>
<p class="ep-h">Query parameters</p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
</div>

    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The user's detail.<span class="r-sig"><a href="#schema-AdminUserDetail">AdminUserDetail</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such user&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminUserDisable">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/user/disable</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Disable or re-enable a user</span>
  </summary>
  <div class="ep-body">
<p>Sets the <code>disabled</code> flag. A disabled account is locked out everywhere at once (every existing session stops resolving) and dropped from live presence. Admins cannot be disabled. Audited.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
  <div class="prow">
    <span class="p-name">disabled<em class="p-req" title="required">required</em></span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Flag updated.<span class="r-sig">{ ok: always true, id: string, disabled: boolean }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Target is an admin.<span class="r-sig"><code>{&quot;error&quot;:&quot;cannot disable an admin&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such user&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminUserDelete">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/user/delete</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Delete a user and everything of theirs</span>
  </summary>
  <div class="ep-body">
<p>Removes the account for good: the user record, their passkeys, their push subscriptions, their live presence, their training history file, their uploaded photos and videos (<code>DATA_DIR/uploads/&lt;uid&gt;/</code>) and any Coach credential stored for them. Not reversible; <code>/api/admin/user/disable</code> is the reversible one. An admin cannot delete their own account, the last admin and the owner cannot be deleted, and only the owner deletes another admin. Audited by name, since the id stops meaning anything.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The account and everything of theirs is gone.<span class="r-sig">{ ok: always true, id: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Your own account, the last admin, or the owner.<span class="r-sig"><code>{&quot;error&quot;:&quot;you cannot delete your own account&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such user&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminUserRole">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/user/role</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Owner: make someone an admin, or remove the role</span>
  </summary>
  <div class="ep-body">
<p>Owner only (403 for any other admin). Not on the owner themselves, not on an admin named in <code>ADMIN_UIDS</code> (the server would restore them on restart), and a disabled account is enabled before it can be promoted. Removing the role keeps the account and its data.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
  <div class="prow">
    <span class="p-name">admin<em class="p-req" title="required">required</em></span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Changed.<span class="r-sig">{ ok: always true, id: string, admin: boolean }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The owner, an <code>ADMIN_UIDS</code> admin, a disabled account, or no boolean.</span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.</span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminOwnerTransfer">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/owner</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Owner: hand the owner role to another admin</span>
  </summary>
  <div class="ep-body">
<p>Owner only. The target must already be an enabled admin; the previous owner stays an admin.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">The user id.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Handed over.<span class="r-sig">{ ok: always true, id: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Yourself, or not an enabled admin.</span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No user with that id.</span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminInvites">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/admin/invites</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">List invite codes</span>
  </summary>
  <div class="ep-body">
<p>All invite codes, with the redeeming user's name resolved for display.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">All invites.<span class="r-sig">{ invites: <a href="#schema-Invite">Invite</a>[], invite_only: boolean }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminInviteNew">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/invites/new</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Mint an invite code</span>
  </summary>
  <div class="ep-body">
<p>Creates a fresh single-use invite code (16 hex chars = 64 bits; the code itself is the thing that isn't worth guessing; rate limiting is the reverse proxy's job). Audited.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">note</span>
    <span class="p-type">string <span class="p-hint">(&le; 60 chars)</span></span>
    <span class="p-desc">Free-form label (&quot;for Alex&quot;).</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The new invite.<span class="r-sig">{ invite: <a href="#schema-Invite">Invite</a> }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminInviteRevoke">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/invites/revoke</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Revoke an unused invite code</span>
  </summary>
  <div class="ep-body">
<p>Deletes an unused code. A code that was already redeemed cannot be revoked.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">code<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Revoked.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">The code was already used.<span class="r-sig"><code>{&quot;error&quot;:&quot;already used, cannot revoke&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">404</span>
    <span class="p-desc">No such code.<span class="r-sig"><code>{&quot;error&quot;:&quot;no such code&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminAudit">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/admin/audit</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Read the activity log</span>
  </summary>
  <div class="ep-body">
<p>The audit log (sign-ins, failed attempts, admin actions), newest first, paged by event id (<code>before</code> cursor; offset paging would repeat rows as new events land). Retention (<code>AUDIT_MAX</code> events / <code>AUDIT_DAYS</code> days) is applied on read as well as on the hourly compaction. When <code>AUDIT_LOG</code> is off the route still answers, with <code>enabled: false</code> and whatever was logged before.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>
<p class="ep-h">Query parameters</p><div class="ptab">
  <div class="prow">
    <span class="p-name">limit</span>
    <span class="p-type">integer <span class="p-hint">(1&ndash;200, default 100)</span></span>
    <span class="p-desc">Page size.</span>
  </div>
  <div class="prow">
    <span class="p-name">before</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Only events with id &lt; before (cursor from <code>nextBefore</code>).</span>
  </div>
  <div class="prow">
    <span class="p-name">cat</span>
    <span class="p-type">&quot;auth&quot; | &quot;admin&quot; | &quot;fail&quot;</span>
    <span class="p-desc">Filter: <code>fail</code> keeps only failed events; any other value keeps events whose name starts with <code>&lt;cat&gt;.</code> (in practice <code>auth</code> or <code>admin</code>).</span>
  </div>
</div>

    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">One page of the log.<span class="r-sig">{ events: <a href="#schema-AuditEvent">AuditEvent</a>[], total: integer, nextBefore: integer | null, enabled: boolean, ip_mode: &quot;off&quot; | &quot;net&quot; | &quot;full&quot;, retention: object, now: number }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-adminAuditClear">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/audit/clear</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Owner: clear the activity log</span>
  </summary>
  <div class="ep-body">
<p>Owner only, so no other admin can erase a trace of what they did. Deletes the log file. The clear is itself the first event of the fresh log, and event ids are never reset, so a wipe always leaves a visible id gap.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Cleared.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-getAdminCoach">
  <summary>
    <span class="m get">GET</span>
    <span class="ep-path"><code>/api/admin/coach</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The Coach card</span>
  </summary>
  <div class="ep-body">
<p>Everything the admin screen renders in one round trip, including a live check of the configured provider: for a runtime provider &quot;is the runtime there&quot;, for an HTTPS one the model list its stored key can see. A runtime-backed provider is not run when the privilege drop cannot be performed, exactly as a job would not be: <code>runtime</code> then reads unavailable, with the same reason a job is refused with.</p>
<p>Counts and outcomes only: no intake answers, no payloads, no proposals, and never a credential, only whether one is filed and what it is labelled.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The card.<span class="r-sig"><a href="#schema-AdminCoach">AdminCoach</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postAdminCoachConfig">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/coach/config</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Change the Coach settings</span>
  </summary>
  <div class="ep-body">
<p>A patch: every field is optional and only what is sent is changed. Model, endpoint and credential are all keyed by provider, so switching provider never drops any of them.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">enabled</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">provider</span>
    <span class="p-type">string</span>
    <span class="p-desc">Must be one of the ids GET /api/admin/coach lists.</span>
  </div>
  <div class="prow">
    <span class="p-name">model</span>
    <span class="p-type">string <span class="p-hint">(&le; 80 chars)</span></span>
    <span class="p-desc">For the provider being set (or the current one). Empty string clears it.</span>
  </div>
  <div class="prow">
    <span class="p-name">baseUrl</span>
    <span class="p-type">string</span>
    <span class="p-desc">Only for a provider with a configurable endpoint; validated before it is stored. Empty means &quot;back to the default&quot;, so it is refused for a provider that has none.</span>
  </div>
  <div class="prow">
    <span class="p-name">community</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Offer the cohort comparison on this instance.</span>
  </div>
  <div class="prow">
    <span class="p-name">caps</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">caps.perProfileDaily</span>
    <span class="p-type">integer <span class="p-hint">(0&ndash;200)</span></span>
    <span class="p-desc">0 = no cap.</span>
  </div>
  <div class="prow">
    <span class="p-name">caps.instanceDaily</span>
    <span class="p-type">integer <span class="p-hint">(0&ndash;5000)</span></span>
    <span class="p-desc">0 = no cap.</span>
  </div>
  <div class="prow">
    <span class="p-name">maxMessageLen</span>
    <span class="p-type">integer <span class="p-hint">(200&ndash;4000)</span></span>
    <span class="p-desc">How long a chat message, refinement or review note can be. Clamped into the range; not a number keeps the current value.</span>
  </div>
</div>
<pre><code>{
  &quot;enabled&quot;: true,
  &quot;provider&quot;: &quot;compatible&quot;,
  &quot;model&quot;: &quot;qwen3.8-27b&quot;,
  &quot;caps&quot;: {
    &quot;perProfileDaily&quot;: 10,
    &quot;instanceDaily&quot;: 0
  }
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Saved.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Unknown provider, an endpoint set on a provider that has a fixed one, a base URL that did not validate, or an empty one for a provider with no default endpoint to fall back to (<code>compatible</code>).<span class="r-sig"><code>{&quot;error&quot;:&quot;unknown provider&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postAdminCoachTest">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/coach/test</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Run one round trip against the provider</span>
  </summary>
  <div class="ep-body">
<p>Checks the runtime, then asks the model for one fixed JSON object and validates the shape that comes back. That is the whole path a job takes, on nobody's profile. A runtime-backed provider is refused, without spawning anything, when the privilege drop cannot be performed, exactly as a job would be.</p>
<p>Always 200: the outcome is in the body, because &quot;the provider refused&quot; is an answer to the question the button asks, not a failure of the request. An HTTPS provider gets the same retries as a job: a 429, 500, 502, 503, 504 or 529 is tried twice more, after pauses of 2 and 5 seconds, and only then reported. A runtime provider is asked once.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The result of the round trip.<span class="r-sig">{ ok: boolean, version: string, error: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postAdminCoachModels">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/coach/models</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">List the models the endpoint serves</span>
  </summary>
  <div class="ep-body">
<p>So the card can offer a list rather than a text field that goes stale with every model release. HTTPS providers only; a provider that cannot be asked answers <code>ok: false</code> with an empty list rather than an error status.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>


    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">The models, or why there are none.<span class="r-sig">{ ok: boolean, models: string[], error: string }</span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postAdminCoachConnect">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/coach/connect</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">File the provider credential</span>
  </summary>
  <div class="ep-body">
<p>The token is accepted once and never read back: it is encrypted with the instance secret and leaves again only as an environment variable on a job's child process. <code>type</code> has to match a variable the provider actually declares, so a key for one provider cannot be filed under another and then silently go nowhere.</p>
<p>A key may be filed for a provider that is not the active one, so the chips can be prepared before switching.</p>
    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">provider</span>
    <span class="p-type">string</span>
    <span class="p-desc">Defaults to the active provider.</span>
  </div>
  <div class="prow">
    <span class="p-name">type<em class="p-req" title="required">required</em></span>
    <span class="p-type">&quot;cli-token&quot; | &quot;oauth&quot; | &quot;apikey&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">token<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">Never returned by any route, ever.</span>
  </div>
  <div class="prow">
    <span class="p-name">account</span>
    <span class="p-type">string <span class="p-hint">(&le; 120 chars)</span></span>
    <span class="p-desc">A label for whose account this is, shown on the card.</span>
  </div>
</div>
<pre><code>{
  &quot;type&quot;: &quot;apikey&quot;,
  &quot;token&quot;: &quot;sk-…&quot;,
  &quot;account&quot;: &quot;[email protected]&quot;
}</code></pre>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Filed.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Unknown provider, a credential type that provider does not take, or no token.<span class="r-sig"><code>{&quot;error&quot;:&quot;no token supplied&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>

<details class="ep" id="op-postAdminCoachDisconnect">
  <summary>
    <span class="m post">POST</span>
    <span class="ep-path"><code>/api/admin/coach/disconnect</code><span class="ep-chip admin">admin</span></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Remove the provider credential</span>
  </summary>
  <div class="ep-body">

    <p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Admin only: a signed-in session whose user is an admin (<code>ADMIN_UIDS</code> or <code>admin:true</code>), as the session cookie or a Bearer token.</span></p>

<p class="ep-h">Request body <span class="p-hint">(JSON)</span> <span class="p-hint">(optional)</span></p><div class="ptab">
  <div class="prow">
    <span class="p-name">provider</span>
    <span class="p-type">string</span>
    <span class="p-desc">Defaults to the active provider.</span>
  </div>
</div>
    <p class="ep-h">Responses</p>
    <div class="ptab">
  <div class="prow rrow">
    <span class="r-code s2">200</span>
    <span class="p-desc">Removed.<span class="r-sig"><a href="#schema-Ok">Ok</a></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">400</span>
    <span class="p-desc">Unknown provider.<span class="r-sig"><code>{&quot;error&quot;:&quot;unknown provider&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">401</span>
    <span class="p-desc">No session, expired/revoked session, or a disabled account.<span class="r-sig"><code>{&quot;error&quot;:&quot;not signed in&quot;}</code></span></span>
  </div>
  <div class="prow rrow">
    <span class="r-code s4">403</span>
    <span class="p-desc">Signed in, but not an admin. The attempt is recorded in the audit log.<span class="r-sig"><code>{&quot;error&quot;:&quot;forbidden&quot;}</code></span></span>
  </div>
    </div>
  </div>
</details>
  </div>
</section>

  <section class="api-sec" id="schemas">
    <h2>Schemas</h2>
    <p class="sub">The named shapes the endpoints above link to. The <code>State</code> blob
       is <b>representative, not enforced</b>: the server stores it opaquely and the app
       grows it over time.</p>
    <div class="eps">

<details class="ep sch" id="schema-Error">
  <summary>
    <span class="sch-name"><code>Error</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">error<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">Human-readable message. This is the only error shape the API has.</span>
  </div>
  <div class="prow">
    <span class="p-name">code</span>
    <span class="p-type">string</span>
    <span class="p-desc">A stable reason on the password, throttle and media routes, for a client to word in its own language (<code>bad-credentials</code>, <code>locked</code>, <code>too-short</code>, <code>media-quota</code>, …). Media refusals add the numbers to word it with (<code>maxMB</code>, <code>maxSec</code>, <code>usedMB</code>, <code>quotaMB</code>).</span>
  </div>
  <div class="prow">
    <span class="p-name">retryAfter</span>
    <span class="p-type">integer</span>
    <span class="p-desc">429 only. The same number of seconds as the Retry-After header.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-Ok">
  <summary>
    <span class="sch-name"><code>Ok</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">ok</span>
    <span class="p-type">always true</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-PasskeyList">
  <summary>
    <span class="sch-name"><code>PasskeyList</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">passkeys</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">passkeys[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc">WebAuthn credential id (base64url).</span>
  </div>
  <div class="prow">
    <span class="p-name">passkeys[].name</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">passkeys[].created</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">ISO timestamp.</span>
  </div>
  <div class="prow">
    <span class="p-name">passkeys[].lastUsed</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">ISO timestamp of the last sign-in or confirmation with it.</span>
  </div>
  <div class="prow">
    <span class="p-name">passkeys[].transports</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">password</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">The profile has a password and <code>PASSWORD_LOGIN</code> is on, so <code>current</code> can prove an addition or a removal.</span>
  </div>
  <div class="prow">
    <span class="p-name">lastWayIn</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Removing any one passkey would be refused (409 <code>last-way-in</code>).</span>
  </div>
  <div class="prow">
    <span class="p-name">deleteBlocked</span>
    <span class="p-type">&quot;last-admin&quot;</span>
    <span class="p-desc">Present when deleting this profile (<code>POST /api/account/delete</code>) would be refused before any proof is checked: <code>last-admin</code>, the only admin while other profiles remain. The delete sheet says so before asking for a passkey or the password; the delete itself still checks.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-OwnerProof">
  <summary>
    <span class="sch-name"><code>OwnerProof</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Either a passkey assertion made for this request (<code>cid</code> + <code>credential</code>), or the profile's current password (<code>current</code>), which counts only while <code>PASSWORD_LOGIN</code> is on.</span>
  </summary>
  <div class="ep-body">
<p>Each assertion is good for one request: its challenge is spent by it.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">cid</span>
    <span class="p-type">string</span>
    <span class="p-desc">From POST /api/login/options.</span>
  </div>
  <div class="prow">
    <span class="p-name">credential</span>
    <span class="p-type"><a href="#schema-WebAuthnAuthenticationCredential">WebAuthnAuthenticationCredential</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">current</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-SessionUser">
  <summary>
    <span class="sch-name"><code>SessionUser</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The caller's identity, as returned by /api/me and the sign-in routes.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc">Stable user id (16 base64url chars).</span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">owner</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Present (true) only for the instance owner.</span>
  </div>
  <div class="prow">
    <span class="p-name">admin</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-WebAuthnRegistrationOptions">
  <summary>
    <span class="sch-name"><code>WebAuthnRegistrationOptions</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">PublicKeyCredentialCreationOptionsJSON.</span>
  </summary>
  <div class="ep-body">
<p>Pass to <code>startRegistration()</code> (@simplewebauthn/browser) or decode for <code>navigator.credentials.create()</code>. Resident keys are required; attestation is <code>none</code>.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">challenge</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url</span>
  </div>
  <div class="prow">
    <span class="p-name">rp</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">rp.name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">rp.id</span>
    <span class="p-type">string</span>
    <span class="p-desc">The RP_ID the instance is configured with.</span>
  </div>
  <div class="prow">
    <span class="p-name">user</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.id</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url user handle</span>
  </div>
  <div class="prow">
    <span class="p-name">user.name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.displayName</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">pubKeyCredParams</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">authenticatorSelection</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">authenticatorSelection.residentKey</span>
    <span class="p-type">always &quot;required&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">authenticatorSelection.userVerification</span>
    <span class="p-type">always &quot;preferred&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">attestation</span>
    <span class="p-type">always &quot;none&quot;</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-WebAuthnRegistrationCredential">
  <summary>
    <span class="sch-name"><code>WebAuthnRegistrationCredential</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">RegistrationResponseJSON: the value <code>startRegistration()</code> resolves with (the created credential plus the authenticator's attestation response), sent back verbatim.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url credential id</span>
  </div>
  <div class="prow">
    <span class="p-name">rawId</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">type</span>
    <span class="p-type">always &quot;public-key&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response.clientDataJSON</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url</span>
  </div>
  <div class="prow">
    <span class="p-name">response.attestationObject</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url</span>
  </div>
  <div class="prow">
    <span class="p-name">response.transports</span>
    <span class="p-type">string[]</span>
    <span class="p-desc">e.g. [&quot;internal&quot;, &quot;hybrid&quot;], stored for later logins.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-WebAuthnAuthenticationOptions">
  <summary>
    <span class="sch-name"><code>WebAuthnAuthenticationOptions</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">PublicKeyCredentialRequestOptionsJSON.</span>
  </summary>
  <div class="ep-body">
<p>Pass to <code>startAuthentication()</code>. <code>allowCredentials</code> is empty: the browser offers the user's discoverable passkeys itself.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">challenge</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url</span>
  </div>
  <div class="prow">
    <span class="p-name">rpId</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">userVerification</span>
    <span class="p-type">always &quot;preferred&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">allowCredentials</span>
    <span class="p-type">object[]</span>
    <span class="p-desc">Always empty.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-WebAuthnAuthenticationCredential">
  <summary>
    <span class="sch-name"><code>WebAuthnAuthenticationCredential</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">AuthenticationResponseJSON: the value <code>startAuthentication()</code> resolves with, sent back verbatim.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc">base64url credential id</span>
  </div>
  <div class="prow">
    <span class="p-name">rawId</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">type</span>
    <span class="p-type">always &quot;public-key&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response.clientDataJSON</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response.authenticatorData</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response.signature</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">response.userHandle</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-State">
  <summary>
    <span class="sch-name"><code>State</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The whole app state as one blob.</span>
  </summary>
  <div class="ep-body">
<p>The server treats it as opaque (it only strips <code>active</code> on save and reads a few fields for reminders and the admin dashboard). The schema below is <b>representative, not enforced</b> (except <code>workouts</code> and <code>routines</code>, which must be arrays (or null) when present), and grows with the app. Concurrent writes are caught by the server's revision (<code>_rev</code>, see PUT /api/data); the client merges the two documents and decides by <code>_ts</code> which side's settings win.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">_ts</span>
    <span class="p-type">number</span>
    <span class="p-desc">Client-set last-write timestamp (ms since epoch); drives sync.</span>
  </div>
  <div class="prow">
    <span class="p-name">_rev</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Server-set revision, incremented on every accepted PUT. Ignored when sent by a client.</span>
  </div>
  <div class="prow">
    <span class="p-name">_wid</span>
    <span class="p-type">string</span>
    <span class="p-desc">Server-set id of this write (16 hex characters), new on every accepted PUT.</span>
  </div>
  <div class="prow">
    <span class="p-name">_wids</span>
    <span class="p-type">string[]</span>
    <span class="p-desc">The write ids of the documents this one descends from, oldest first (up to 50).</span>
  </div>
  <div class="prow">
    <span class="p-name">deleted</span>
    <span class="p-type">object</span>
    <span class="p-desc">When entries were removed, per list and entry key ({ workouts: { &lt;id&gt;: ms } }, weigh-ins by day, favourites by exercise id). A negative stamp is an add-back after a removal. Never shrinks on the server; stamped for writers that do not stamp (see PUT /api/data).</span>
  </div>
  <div class="prow">
    <span class="p-name">edited</span>
    <span class="p-type">object</span>
    <span class="p-desc">When each setting and plan day was last changed, ms ({ queue: ms, 'week.3': ms, … }). Never shrinks on the server; stamped for writers that do not stamp (see PUT /api/data).</span>
  </div>
  <div class="prow">
    <span class="p-name">unit</span>
    <span class="p-type">&quot;kg&quot; | &quot;lb&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">lang</span>
    <span class="p-type">string</span>
    <span class="p-desc">UI language code (&quot;en&quot;, &quot;de&quot;, &quot;pt&quot;, …); also localizes pushes.</span>
  </div>
  <div class="prow">
    <span class="p-name">theme</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">accent</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">workouts</span>
    <span class="p-type"><a href="#schema-Workout">Workout</a>[]</span>
    <span class="p-desc">Completed workouts, chronological.</span>
  </div>
  <div class="prow">
    <span class="p-name">routines</span>
    <span class="p-type"><a href="#schema-Routine">Routine</a>[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">queue</span>
    <span class="p-type">object</span>
    <span class="p-desc">A planner's floating week {ids, since, startsOn, label}. The week's sessions as an ordered queue, the first undone one is today's. Written by an API client or by the app's own rotation feature, read by the reminder tick.</span>
  </div>
  <div class="prow">
    <span class="p-name">week</span>
    <span class="p-type">object</span>
    <span class="p-desc">Weekly plan: weekday (0=Sunday … 6) → routine id.</span>
  </div>
  <div class="prow">
    <span class="p-name">dayPlan</span>
    <span class="p-type">object</span>
    <span class="p-desc">Per-date overrides: ISO date → routine id, or &quot;rest&quot;. Wins over <code>week</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">bodyweight</span>
    <span class="p-type"><a href="#schema-BodyweightEntry">BodyweightEntry</a>[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">customEx</span>
    <span class="p-type"><a href="#schema-CustomExercise">CustomExercise</a>[]</span>
    <span class="p-desc">User-created exercises (id, name, muscles…).</span>
  </div>
  <div class="prow">
    <span class="p-name">exWeights</span>
    <span class="p-type">object</span>
    <span class="p-desc">Per-exercise last/best weight memory: exercise id → {w, d}.</span>
  </div>
  <div class="prow">
    <span class="p-name">reminder</span>
    <span class="p-type">object</span>
    <span class="p-desc">Daily &quot;workout planned today&quot; push. The server reads this: at <code>time</code> (HH:MM, in <code>tz</code>) it sends one push if a routine is planned and nothing was logged yet.</span>
  </div>
  <div class="prow">
    <span class="p-name">reminder.on</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">reminder.time</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">reminder.tz</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">IANA zone (&quot;Europe/Zurich&quot;); the user's own clock.</span>
  </div>
  <div class="prow">
    <span class="p-name">restSec</span>
    <span class="p-type">number</span>
    <span class="p-desc">Default rest-timer seconds.</span>
  </div>
  <div class="prow">
    <span class="p-name">effort</span>
    <span class="p-type">&quot;none&quot; | &quot;rir&quot; | &quot;rpe&quot; | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">equipProfiles</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">settings</span>
    <span class="p-type">object</span>
    <span class="p-desc">Catch-all note: the remaining top-level keys (sound, keepAwake, gifSize, targetW, autoBackup, …) are flat settings values like the ones above.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CustomExercise">
  <summary>
    <span class="sch-name"><code>CustomExercise</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">One exercise the user made (representative shape).</span>
  </summary>
  <div class="ep-body">
<p>The server stores it as sent and reads only <code>media</code> from it, to know which uploaded files are still referenced.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">n</span>
    <span class="p-type">string</span>
    <span class="p-desc">Name.</span>
  </div>
  <div class="prow">
    <span class="p-name">bp</span>
    <span class="p-type">string</span>
    <span class="p-desc">Body part.</span>
  </div>
  <div class="prow">
    <span class="p-name">custom</span>
    <span class="p-type">always true</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">media</span>
    <span class="p-type"><a href="#schema-MediaRef">MediaRef</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">url</span>
    <span class="p-type">string <span class="p-hint">(uri, &le; 2048 chars)</span></span>
    <span class="p-desc">One link: a video or a guide. http(s) only, no credentials. Neither the app nor the server ever fetches it: the app opens it in a new browsing context on a tap.</span>
  </div>
  <div class="prow">
    <span class="p-name">_ts</span>
    <span class="p-type">number</span>
    <span class="p-desc">When this entry was last edited, ms, for merging two devices' copies.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-MediaRef">
  <summary>
    <span class="sch-name"><code>MediaRef</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">What the state knows of an uploaded file.</span>
  </summary>
  <div class="ep-body">
<p>The bytes are behind <code>GET /api/media/{hash}</code>; the server keeps a file as long as some <code>customEx[].media.hash</code>, <code>workouts[].media[].hash</code> or <code>.poster.hash</code> of either in the profile's state names it, and for <code>MEDIA_GC_GRACE_DAYS</code> after.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">kind<em class="p-req" title="required">required</em></span>
    <span class="p-type">&quot;image&quot; | &quot;gif&quot; | &quot;video&quot;</span>
    <span class="p-desc"><code>gif</code> means animated; a one-frame GIF is an <code>image</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">hash<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">SHA-256 of the stored file.</span>
  </div>
  <div class="prow">
    <span class="p-name">mime<em class="p-req" title="required">required</em></span>
    <span class="p-type">&quot;image/webp&quot; | &quot;image/jpeg&quot; | &quot;image/png&quot; | &quot;image/gif&quot; | &quot;video/mp4&quot; | &quot;video/quicktime&quot; | &quot;video/webm&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">size<em class="p-req" title="required">required</em></span>
    <span class="p-type">integer <span class="p-hint">(1&ndash;)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">width<em class="p-req" title="required">required</em></span>
    <span class="p-type">integer <span class="p-hint">(1&ndash;16384)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">height<em class="p-req" title="required">required</em></span>
    <span class="p-type">integer <span class="p-hint">(1&ndash;16384)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">dur</span>
    <span class="p-type">number <span class="p-hint">(0&ndash;3600)</span></span>
    <span class="p-desc">Seconds, one decimal; videos and animated GIFs, absent when unknown.</span>
  </div>
  <div class="prow">
    <span class="p-name">codec</span>
    <span class="p-type">&quot;avc1&quot; | &quot;hvc1&quot; | &quot;av01&quot; | &quot;vp09&quot; | &quot;vp8&quot; | &quot;vp9&quot; | &quot;other&quot;</span>
    <span class="p-desc">Videos only.</span>
  </div>
  <div class="prow">
    <span class="p-name">poster</span>
    <span class="p-type">object</span>
    <span class="p-desc">A still of at most 480 px, always for images and GIFs, when possible for videos.</span>
  </div>
  <div class="prow">
    <span class="p-name">poster.hash</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">poster.mime</span>
    <span class="p-type">&quot;image/webp&quot; | &quot;image/jpeg&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">poster.size</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">poster.width</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">poster.height</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">at<em class="p-req" title="required">required</em></span>
    <span class="p-type">number</span>
    <span class="p-desc">When it was attached</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-MediaConfig">
  <summary>
    <span class="sch-name"><code>MediaConfig</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The instance's media caps (<code>MEDIA_*</code>), in MB of 2^20 bytes.</span>
  </summary>
  <div class="ep-body">
<p>Absent when the instance runs with <code>MEDIA_UPLOADS=0</code>.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">imageMB</span>
    <span class="p-type">number</span>
    <span class="p-desc">A photo after the app re-encoded it, or a poster.</span>
  </div>
  <div class="prow">
    <span class="p-name">gifMB</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">videoMB</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">videoSec</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">quotaMB</span>
    <span class="p-type">number</span>
    <span class="p-desc">Per profile; 0 = no cap.</span>
  </div>
  <div class="prow">
    <span class="p-name">workouts</span>
    <span class="p-type">always true</span>
    <span class="p-desc">This instance keeps the files a logged workout's <code>media</code> list names too, not only a custom exercise's. Absent on an instance from before; the app then offers photos and videos on custom exercises only.</span>
  </div>
  <div class="prow">
    <span class="p-name">days</span>
    <span class="p-type">always true</span>
    <span class="p-desc">This instance also keeps the files of progress photos filed under a day (<code>dayPhotos</code>, a photo for a day without a workout). Absent on an instance from before; the app then only adds photos to logged workouts there.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-MediaUsage">
  <summary>
    <span class="sch-name"><code>MediaUsage</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">bytes</span>
    <span class="p-type">integer</span>
    <span class="p-desc">What the profile's stored files take.</span>
  </div>
  <div class="prow">
    <span class="p-name">count</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">quotaBytes</span>
    <span class="p-type">integer</span>
    <span class="p-desc">The cap; 0 = no cap.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-MediaStored">
  <summary>
    <span class="sch-name"><code>MediaStored</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">ok</span>
    <span class="p-type">always true</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">hash</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">mime</span>
    <span class="p-type">string</span>
    <span class="p-desc">What the bytes are, not necessarily what was declared.</span>
  </div>
  <div class="prow">
    <span class="p-name">size</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">existed</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">The server already had this file.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-Workout">
  <summary>
    <span class="sch-name"><code>Workout</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">One completed workout (representative shape).</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">d</span>
    <span class="p-type">string <span class="p-hint">(date)</span></span>
    <span class="p-desc">ISO day, e.g. &quot;2026-08-30&quot;.</span>
  </div>
  <div class="prow">
    <span class="p-name">start</span>
    <span class="p-type">number</span>
    <span class="p-desc">ms since epoch</span>
  </div>
  <div class="prow">
    <span class="p-name">end</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routineId</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bw</span>
    <span class="p-type">number</span>
    <span class="p-desc">Body weight that day, in <code>unit</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">vol</span>
    <span class="p-type">number</span>
    <span class="p-desc">Total volume (Σ weight × reps).</span>
  </div>
  <div class="prow">
    <span class="p-name">prs</span>
    <span class="p-type">string[]</span>
    <span class="p-desc">Exercise ids that hit a personal record.</span>
  </div>
  <div class="prow">
    <span class="p-name">entries</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc">Exercise id.</span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].topW</span>
    <span class="p-type">number | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets[].w</span>
    <span class="p-type">number</span>
    <span class="p-desc">Weight.</span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets[].r</span>
    <span class="p-type">number</span>
    <span class="p-desc">Reps.</span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets[].done</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets[].rir</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">entries[].sets[].rpe</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">media</span>
    <span class="p-type"><a href="#schema-MediaRef">MediaRef</a>[]</span>
    <span class="p-desc">Photos and videos attached to this workout (a progress photo, a form-check clip), at most six in the app. Refs only; the bytes are behind <code>/api/media/{hash}</code>, and the server keeps every file any entry here names (the GC walks this list as it walks each custom exercise's <code>media</code>).</span>
  </div>
  <div class="prow">
    <span class="p-name">_ts</span>
    <span class="p-type">number</span>
    <span class="p-desc">When this workout was last edited after it was logged, ms, for merging two devices' copies.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-Routine">
  <summary>
    <span class="sch-name"><code>Routine</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">A workout template (representative shape).</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">emoji</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">ex</span>
    <span class="p-type">object[]</span>
    <span class="p-desc">Exercises with set/rep targets.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-BodyweightEntry">
  <summary>
    <span class="sch-name"><code>BodyweightEntry</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">d</span>
    <span class="p-type">string <span class="p-hint">(date)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">w</span>
    <span class="p-type">number</span>
    <span class="p-desc">Weight in <code>unit</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">t</span>
    <span class="p-type">number</span>
    <span class="p-desc">Timestamp (ms).</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-PushSubscription">
  <summary>
    <span class="sch-name"><code>PushSubscription</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The browser's PushSubscription.toJSON(); only these fields are stored.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">endpoint<em class="p-req" title="required">required</em></span>
    <span class="p-type">string <span class="p-hint">(uri)</span></span>
    <span class="p-desc">Public https:// push-service URL.</span>
  </div>
  <div class="prow">
    <span class="p-name">keys<em class="p-req" title="required">required</em></span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">keys.p256dh<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">keys.auth<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-AdminUserRow">
  <summary>
    <span class="sch-name"><code>AdminUserRow</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">created</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">ISO timestamp.</span>
  </div>
  <div class="prow">
    <span class="p-name">disabled</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">owner</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">The one admin who manages the others.</span>
  </div>
  <div class="prow">
    <span class="p-name">admin</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">invitedBy</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">The invite code this account was created with.</span>
  </div>
  <div class="prow">
    <span class="p-name">workouts</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Total logged workouts.</span>
  </div>
  <div class="prow">
    <span class="p-name">lastWorkout</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">ISO day of the newest workout.</span>
  </div>
  <div class="prow">
    <span class="p-name">lastSync</span>
    <span class="p-type">number | null</span>
    <span class="p-desc">The state's <code>_ts</code> (ms).</span>
  </div>
  <div class="prow">
    <span class="p-name">hasPush</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Has at least one push subscription.</span>
  </div>
  <div class="prow">
    <span class="p-name">live</span>
    <span class="p-type"><a href="#schema-Presence">Presence</a> | null</span>
    <span class="p-desc">Currently training, or null.</span>
  </div>
  <div class="prow">
    <span class="p-name">password</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">PASSWORD_LOGIN instances only. The profile has a password.</span>
  </div>
  <div class="prow">
    <span class="p-name">email</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">PASSWORD_LOGIN instances only. The e-mail the profile signs in with, if any.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-Presence">
  <summary>
    <span class="sch-name"><code>Presence</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Live-workout snapshot (from /api/activity heartbeats).</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exIdx</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exTotal</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">setsDone</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">setsTotal</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">startedAt</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">updatedAt</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-AdminUserDetail">
  <summary>
    <span class="sch-name"><code>AdminUserDetail</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">user</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.created</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.disabled</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.owner</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">The one admin who manages the others.</span>
  </div>
  <div class="prow">
    <span class="p-name">user.admin</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.invitedBy</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">user.password</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">PASSWORD_LOGIN instances only.</span>
  </div>
  <div class="prow">
    <span class="p-name">user.email</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">PASSWORD_LOGIN instances only. The sign-in e-mail, if any.</span>
  </div>
  <div class="prow">
    <span class="p-name">user.resetUntil</span>
    <span class="p-type">number | null</span>
    <span class="p-desc">PASSWORD_LOGIN instances only. Expiry (ms) of an unused reset code.</span>
  </div>
  <div class="prow">
    <span class="p-name">user.recoveryUntil</span>
    <span class="p-type">number | null</span>
    <span class="p-desc">Expiry (ms) of an unused recovery code (POST /api/admin/user/recovery, recover.js).</span>
  </div>
  <div class="prow">
    <span class="p-name">unit</span>
    <span class="p-type">&quot;kg&quot; | &quot;lb&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">lastSync</span>
    <span class="p-type">number | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routines</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routines[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routines[].name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routines[].emoji</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">routines[].count</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Number of exercises.</span>
  </div>
  <div class="prow">
    <span class="p-name">bodyweight</span>
    <span class="p-type"><a href="#schema-BodyweightEntry">BodyweightEntry</a>[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">workouts</span>
    <span class="p-type"><a href="#schema-Workout">Workout</a>[]</span>
    <span class="p-desc">Full history, newest first.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-Invite">
  <summary>
    <span class="sch-name"><code>Invite</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">code</span>
    <span class="p-type">string</span>
    <span class="p-desc">16 hex chars.</span>
  </div>
  <div class="prow">
    <span class="p-name">note</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">createdBy</span>
    <span class="p-type">string</span>
    <span class="p-desc">Admin user id.</span>
  </div>
  <div class="prow">
    <span class="p-name">created</span>
    <span class="p-type">string</span>
    <span class="p-desc">ISO timestamp.</span>
  </div>
  <div class="prow">
    <span class="p-name">usedBy</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">User id that redeemed the code (absent/null while unused).</span>
  </div>
  <div class="prow">
    <span class="p-name">usedAt</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">usedByName</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">Resolved display name (only in GET /api/admin/invites).</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-AuditEvent">
  <summary>
    <span class="sch-name"><code>AuditEvent</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">One line of the audit log.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">id<em class="p-req" title="required">required</em></span>
    <span class="p-type">integer</span>
    <span class="p-desc">Monotonic, never reset; a cleared log leaves a visible id gap.</span>
  </div>
  <div class="prow">
    <span class="p-name">ts<em class="p-req" title="required">required</em></span>
    <span class="p-type">number</span>
    <span class="p-desc">ms since epoch.</span>
  </div>
  <div class="prow">
    <span class="p-name">ev<em class="p-req" title="required">required</em></span>
    <span class="p-type">string</span>
    <span class="p-desc">Event name. Currently one of: <code>auth.register.ok|fail|denied</code>, <code>auth.login.ok|fail</code>, <code>auth.logout</code>, <code>auth.logout.all</code>, <code>auth.account.delete</code>, <code>auth.pair.create|ok|fail</code>, <code>admin.denied</code>, <code>admin.user.disable|enable</code>, <code>admin.invite.create|revoke</code>, <code>admin.audit.clear</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">ok<em class="p-req" title="required">required</em></span>
    <span class="p-type">boolean</span>
    <span class="p-desc">false for failed/denied attempts.</span>
  </div>
  <div class="prow">
    <span class="p-name">uid</span>
    <span class="p-type">string</span>
    <span class="p-desc">Acting (or affected) user id.</span>
  </div>
  <div class="prow">
    <span class="p-name">name</span>
    <span class="p-type">string</span>
    <span class="p-desc">Acting user's name (max 40 chars).</span>
  </div>
  <div class="prow">
    <span class="p-name">tgt</span>
    <span class="p-type">string</span>
    <span class="p-desc">Target user id (admin actions).</span>
  </div>
  <div class="prow">
    <span class="p-name">tname</span>
    <span class="p-type">string</span>
    <span class="p-desc">Target user's name.</span>
  </div>
  <div class="prow">
    <span class="p-name">msg</span>
    <span class="p-type">string</span>
    <span class="p-desc">Short detail: a failure reason code, or the invite code involved. Rejected invite guesses and unknown credential ids are deliberately never recorded.</span>
  </div>
  <div class="prow">
    <span class="p-name">ip</span>
    <span class="p-type">string</span>
    <span class="p-desc">Only when AUDIT_IP is on: the full address (<code>full</code>) or just the network, /24 or /48 (<code>net</code>).</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CoachCap">
  <summary>
    <span class="sch-name"><code>CoachCap</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">What this profile has spent of its daily allowance.</span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">used</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">limit</span>
    <span class="p-type">integer</span>
    <span class="p-desc">0 means no per-profile cap.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CoachStatus">
  <summary>
    <span class="sch-name"><code>CoachStatus</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum"></span>
  </summary>
  <div class="ep-body">

<div class="ptab">
  <div class="prow">
    <span class="p-name">job</span>
    <span class="p-type">object | null</span>
    <span class="p-desc">The job running now, or null. One at a time per profile.</span>
  </div>
  <div class="prow">
    <span class="p-name">pending</span>
    <span class="p-type"><a href="#schema-CoachProposal">CoachProposal</a> | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">cap</span>
    <span class="p-type"><a href="#schema-CoachCap">CoachCap</a></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">maxMessageLen</span>
    <span class="p-type">integer <span class="p-hint">(200&ndash;4000)</span></span>
    <span class="p-desc">The longest note or refinement this instance keeps, in characters. It rides on the poll so a chat that is already open follows an admin's change.</span>
  </div>
  <div class="prow">
    <span class="p-name">last</span>
    <span class="p-type">object | null</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CoachProposal">
  <summary>
    <span class="sch-name"><code>CoachProposal</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The answer waiting for a decision, from whichever kind of job produced it.</span>
  </summary>
  <div class="ep-body">
<p>It expires 14 days after it was made; the first status poll after that retires it. <code>changes</code> comes from a review, <code>bundle</code> from a plan, <code>score</code>/<code>highlights</code> from a debrief. One of the three, never more.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">id</span>
    <span class="p-type">string</span>
    <span class="p-desc">The job's id.</span>
  </div>
  <div class="prow">
    <span class="p-name">kind</span>
    <span class="p-type">&quot;create&quot; | &quot;review&quot; | &quot;debrief&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">createdAt</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Epoch ms.</span>
  </div>
  <div class="prow">
    <span class="p-name">expiresAt</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Epoch ms.</span>
  </div>
  <div class="prow">
    <span class="p-name">planHash</span>
    <span class="p-type">string</span>
    <span class="p-desc">The plan this was written against. A later edit makes it stale.</span>
  </div>
  <div class="prow">
    <span class="p-name">iteration</span>
    <span class="p-type">integer</span>
    <span class="p-desc">1, or higher after a refine.</span>
  </div>
  <div class="prow">
    <span class="p-name">trigger</span>
    <span class="p-type">&quot;scheduled&quot;</span>
    <span class="p-desc">Present when an automatic review made it, which nobody was watching for.</span>
  </div>
  <div class="prow">
    <span class="p-name">summary</span>
    <span class="p-type">string <span class="p-hint">(&le; 1200 chars)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">changes</span>
    <span class="p-type">object[]</span>
    <span class="p-desc">A review's change-set, each one applied or rejected on its own.</span>
  </div>
  <div class="prow">
    <span class="p-name">changes[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">changes[].type</span>
    <span class="p-type">&quot;add-exercise&quot; | &quot;remove-exercise&quot; | &quot;swap-exercise&quot; | &quot;sets&quot; | &quot;reps&quot; | &quot;repsMin&quot; | &quot;repsMax&quot; | &quot;sec&quot; | &quot;cardio&quot; | &quot;reorder&quot; | &quot;superset&quot; | &quot;routine-prog&quot; | &quot;exercise-prog&quot; | &quot;inc&quot; | &quot;add-routine&quot; | &quot;remove-routine&quot; | &quot;rename-routine&quot; | &quot;week&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">changes[].why</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">changes[].before</span>
    <span class="p-type">object</span>
    <span class="p-desc">What the plan says now. The client checks it before applying.</span>
  </div>
  <div class="prow">
    <span class="p-name">changes[].after</span>
    <span class="p-type">object</span>
    <span class="p-desc">What it would say.</span>
  </div>
  <div class="prow">
    <span class="p-name">evidence</span>
    <span class="p-type">object</span>
    <span class="p-desc">The window the review read.</span>
  </div>
  <div class="prow">
    <span class="p-name">evidence.from</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">evidence.to</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">evidence.sessions</span>
    <span class="p-type">integer | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">notes</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle</span>
    <span class="p-type">object</span>
    <span class="p-desc">A whole plan, from a <code>create</code> job (routines, week and any custom exercises).</span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.opengym_plan</span>
    <span class="p-type">always 1</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.name</span>
    <span class="p-type">string <span class="p-hint">(&le; 40 chars)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.summary</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.basedOn</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.week</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.routines</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">bundle.customEx</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">score</span>
    <span class="p-type">integer <span class="p-hint">(1&ndash;10)</span></span>
    <span class="p-desc">A debrief's score for the session.</span>
  </div>
  <div class="prow">
    <span class="p-name">highlights</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">watch</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">nextTime</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">workout</span>
    <span class="p-type">object</span>
    <span class="p-desc">Which session a debrief read.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CoachIntake">
  <summary>
    <span class="sch-name"><code>CoachIntake</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The intake answers, as the plan screen collects them.</span>
  </summary>
  <div class="ep-body">
<p>Stored in the profile's own state as well; sent here so a plan can be asked for with answers that have not been synced yet.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">goal</span>
    <span class="p-type">string</span>
    <span class="p-desc">e.g. <code>muscle</code>, <code>strength</code>, <code>fat-loss</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">experience</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">daysPerWeek</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">preferredDays</span>
    <span class="p-type">integer[]</span>
    <span class="p-desc">0 = Sunday.</span>
  </div>
  <div class="prow">
    <span class="p-name">sessionMin</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Minutes per session.</span>
  </div>
  <div class="prow">
    <span class="p-name">equipment</span>
    <span class="p-type">string[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">limitations</span>
    <span class="p-type">string</span>
    <span class="p-desc">Injuries and anything to work around.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-CoachCohort">
  <summary>
    <span class="sch-name"><code>CoachCohort</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">Medians across the profiles that opted in, and where this one stands among them.</span>
  </summary>
  <div class="ep-body">
<p><code>ok</code> is false whenever there is nothing to show, and the other flags say why: the admin has the comparison switched off (<code>enabled: false</code>), this profile does not share (<code>sharing: false</code>), or there are not yet three who do.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">ok</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">enabled</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">sharing</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">people</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">minPeople</span>
    <span class="p-type">integer</span>
    <span class="p-desc">Three. Below it nothing is computed at all.</span>
  </div>
  <div class="prow">
    <span class="p-name">unit</span>
    <span class="p-type">&quot;kg&quot; | &quot;lb&quot;</span>
    <span class="p-desc">The reader's own unit. Every number below is in it.</span>
  </div>
  <div class="prow">
    <span class="p-name">sessionsPerWeek</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">sessionsPerWeek.median</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">sessionsPerWeek.you</span>
    <span class="p-type">number</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises</span>
    <span class="p-type">object[]</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises[].name</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises[].people</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises[].median</span>
    <span class="p-type">number | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">exercises[].you</span>
    <span class="p-type">number | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">rankPct</span>
    <span class="p-type">integer | null</span>
    <span class="p-desc">Share of the others at or below this profile, averaged over the listed exercises.</span>
  </div>
</div>
  </div>
</details>

<details class="ep sch" id="schema-AdminCoach">
  <summary>
    <span class="sch-name"><code>AdminCoach</code></span>
    <span class="ep-chev" aria-hidden="true"></span>
    <span class="ep-sum">The whole admin card in one answer.</span>
  </summary>
  <div class="ep-body">
<p>Never a credential, only whether one is filed.</p>
<div class="ptab">
  <div class="prow">
    <span class="p-name">disabledByEnv</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">COACH_DISABLED is set, so nothing the admin toggles matters.</span>
  </div>
  <div class="prow">
    <span class="p-name">enabled</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">provider</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers</span>
    <span class="p-type">object[]</span>
    <span class="p-desc">Every provider this build knows, and what each one needs.</span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].id</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].label</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].runtime</span>
    <span class="p-type">string</span>
    <span class="p-desc">The runtime it spawns, when it spawns one.</span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].setupToken</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].deviceLogin</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].apiKey</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].http</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].baseUrl</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Whether its endpoint is configurable.</span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].keyOptional</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].keyPlaceholder</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].defaultModel</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">providers[].connected</span>
    <span class="p-type">boolean</span>
    <span class="p-desc">Whether a credential is already filed for it.</span>
  </div>
  <div class="prow">
    <span class="p-name">model</span>
    <span class="p-type">string</span>
    <span class="p-desc">The model in force for the active provider.</span>
  </div>
  <div class="prow">
    <span class="p-name">models</span>
    <span class="p-type">object</span>
    <span class="p-desc">Model per provider. Switching provider keeps them all.</span>
  </div>
  <div class="prow">
    <span class="p-name">baseUrl</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">knownModels</span>
    <span class="p-type">string[] | null</span>
    <span class="p-desc">From the live check, when the provider could be asked.</span>
  </div>
  <div class="prow">
    <span class="p-name">caps</span>
    <span class="p-type">object</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">caps.perProfileDaily</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">caps.instanceDaily</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">maxMessageLen</span>
    <span class="p-type">integer</span>
    <span class="p-desc">How long a chat message, refinement or review note can be (200–4000, default 1000).</span>
  </div>
  <div class="prow">
    <span class="p-name">community</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">runtime</span>
    <span class="p-type">object</span>
    <span class="p-desc">The live check performed while answering this request.</span>
  </div>
  <div class="prow">
    <span class="p-name">runtime.ok</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">runtime.version</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">runtime.error</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">runtime.needsKey</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">authMode</span>
    <span class="p-type">&quot;instance&quot; | &quot;profile&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">boundUid</span>
    <span class="p-type">string | null</span>
    <span class="p-desc">The profile an instance credential bound itself to, once one has spent it.</span>
  </div>
  <div class="prow">
    <span class="p-name">auth</span>
    <span class="p-type">object</span>
    <span class="p-desc">Whether a credential is filed, and whose. <code>unreadable</code> is its own state because it has a specific cause and a specific fix: ./data restored without its <code>secret</code>.</span>
  </div>
  <div class="prow">
    <span class="p-name">auth.state</span>
    <span class="p-type">&quot;not-required&quot; | &quot;none&quot; | &quot;optional&quot; | &quot;connected&quot; | &quot;unreadable&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">auth.type</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">auth.account</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">auth.connectedAt</span>
    <span class="p-type">string <span class="p-hint">(date-time)</span> | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">unprivileged</span>
    <span class="p-type">object</span>
    <span class="p-desc">Whether the privilege drop can be performed. It fails closed: if <code>ok</code> is false no job runs at all, and the admin needs to hear that here rather than from a user.</span>
  </div>
  <div class="prow">
    <span class="p-name">unprivileged.ok</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">unprivileged.dropped</span>
    <span class="p-type">boolean</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">unprivileged.why</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">jobsToday</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">lastSuccess</span>
    <span class="p-type">string <span class="p-hint">(date-time)</span> | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">lastError</span>
    <span class="p-type">object</span>
    <span class="p-desc">The last failure the instance log recorded, or null.</span>
  </div>
  <div class="prow">
    <span class="p-name">recent</span>
    <span class="p-type">object[]</span>
    <span class="p-desc">The last 20 jobs, newest first. Counts and outcomes only, never contents.</span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].at</span>
    <span class="p-type">string <span class="p-hint">(date-time)</span></span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].kind</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].trigger</span>
    <span class="p-type">&quot;manual&quot; | &quot;scheduled&quot;</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].outcome</span>
    <span class="p-type">string</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].errorClass</span>
    <span class="p-type">string | null</span>
    <span class="p-desc"></span>
  </div>
  <div class="prow">
    <span class="p-name">recent[].ms</span>
    <span class="p-type">integer</span>
    <span class="p-desc"></span>
  </div>
</div>
  </div>
</details>
    </div>
  </section>
</main>

<footer><div class="wrap foot">
  <span class="c">openGym · AGPL-3.0 · © 2026 <a href="https://duarte-santos.ch" rel="noopener">Duarte Santos</a></span>
  <div class="links">
    <a href="docs.html">Docs</a>
    <a href="about.html">About</a>
    <a href="privacy.html">Privacy</a>
    <a href="https://github.com/DuarteSantos8/openGym" rel="noopener">GitHub</a>
    <a href="https://gitlab.com/DuarteSantos8/opengym" rel="noopener">GitLab mirror</a>
    <a href="https://discord.gg/e62jY6fwVb" rel="noopener">Discord</a>
    <a href="/#download">Download</a>
  </div>
</div></footer>

<script src="site.js?v=28" defer></script>
<script>
/* Jumping to an anchor inside a collapsed card opens the card and re-aligns, since
   the browser scrolled to where the target was while it was still collapsed. */
;(() => {
  const openTo = id => {
    const el = id && document.getElementById(id)
    if (!el) return
    let opened = false
    for (let d = el.closest('details'); d; d = d.parentElement && d.parentElement.closest('details')) {
      if (!d.open) { d.open = true; opened = true }
    }
    // 'instant' on purpose: html has scroll-behavior:smooth, and an animated
    // re-align races the jump the browser already started.
    if (opened) requestAnimationFrame(() => el.scrollIntoView({ block: 'start', behavior: 'instant' }))
  }
  addEventListener('hashchange', () => openTo(location.hash.slice(1)))
  document.addEventListener('click', e => {
    const a = e.target.closest('a[href^="#"]')
    if (a) openTo(a.getAttribute('href').slice(1))
  })
  openTo(location.hash.slice(1))
})()

/* Expand / collapse every card at once. */
document.querySelectorAll('[data-xall]').forEach(b => b.addEventListener('click', () => {
  document.querySelectorAll('details.ep').forEach(d => { d.open = b.dataset.xall === '1' })
}))
</script>
</body>
</html>