346 lines
20 KiB
HTML
346 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>02 Health - Momentry API Docs</title>
|
|
<style>
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
|
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
|
h1 { font-size: 24px; margin: 24px 0 12px; }
|
|
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
|
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
|
p { line-height: 1.6; margin: 8px 0; }
|
|
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
|
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
|
th { background: #f0f0f0; font-weight: 600; }
|
|
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
|
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
|
pre code { background: none; padding: 0; }
|
|
a { color: #0066cc; }
|
|
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
|
.back:hover { color: #333; }
|
|
.topbar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }
|
|
.logout-btn { font-size: 13px; color: #999; text-decoration: none; }
|
|
.logout-btn:hover { color: #cc0000; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<div class="topbar">
|
|
<a class="back" href="index.html">← Back to index</a>
|
|
<a class="logout-btn" href="#" onclick="fetch('/api/v1/auth/logout',{method:'POST'}).then(()=>window.location.reload());return false">Logout</a>
|
|
</div>
|
|
<!-- module: health -->
|
|
<!-- description: Health check endpoints -->
|
|
<!-- depends: 01_auth -->
|
|
|
|
<h2>Health Check</h2>
|
|
<h3><code>GET /health</code></h3>
|
|
<p><strong>Auth</strong>: Public
|
|
<strong>Scope</strong>: system-level</p>
|
|
<p>Returns basic server health status — used by load balancers and monitoring.</p>
|
|
<h4>Example</h4>
|
|
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/health"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{status, version}'</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response (200)</h4>
|
|
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"build_git_hash"</span><span class="p">:</span><span class="w"> </span><span class="s2">"3a6c1865"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"build_timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-16T13:38:15Z"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"uptime_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">3015</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>status</code></td>
|
|
<td>string</td>
|
|
<td><code>ok</code> or <code>degraded</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>version</code></td>
|
|
<td>string</td>
|
|
<td>Semver version</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>build_git_hash</code></td>
|
|
<td>string</td>
|
|
<td>Git commit hash</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>build_timestamp</code></td>
|
|
<td>string</td>
|
|
<td>Binary build time</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>uptime_ms</code></td>
|
|
<td>integer</td>
|
|
<td>Milliseconds since server start</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr />
|
|
<h3><code>GET /health/detailed</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: system-level</p>
|
|
<p>Returns full system health including each service status, resource utilization, pipeline readiness, schema migration status, identity file sync status, and external integrations.</p>
|
|
<blockquote>
|
|
<p>Requires authentication (JWT, session cookie, or API key). The basic <code>/health</code> endpoint remains public for load balancer checks.</p>
|
|
</blockquote>
|
|
<h4>Example</h4>
|
|
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/health/detailed"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{status, services, resources: {cpu: .resources.cpu_used_percent, memory: .resources.memory_used_percent}}'</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response (200)</h4>
|
|
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"services"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"postgres"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"redis"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"qdrant"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"latency_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">5</span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"resources"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"cpu_used_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">12.5</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"memory_available_mb"</span><span class="p">:</span><span class="w"> </span><span class="mi">32768</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"memory_used_percent"</span><span class="p">:</span><span class="w"> </span><span class="mf">31.7</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"pipeline"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"scripts_ready"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scripts_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">345</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"processors"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"asr"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"yolo"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"face"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"pose"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"ocr"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"cut"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scene"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"asrx"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"visual_chunk"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"models_ready"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"models_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">42</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scripts_integrity"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">"matched"</span><span class="p">:</span><span class="w"> </span><span class="mi">332</span><span class="p">,</span><span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">345</span><span class="p">,</span><span class="w"> </span><span class="nt">"ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"ffmpeg"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"schema"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"table_exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"applied"</span><span class="p">:</span><span class="w"> </span><span class="p">[{</span><span class="nt">"filename"</span><span class="p">:</span><span class="w"> </span><span class="s2">"migrate_add_users_table.sql"</span><span class="p">}],</span>
|
|
<span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
|
|
<span class="w"> </span><span class="nt">"ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"identities"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"directory_exists"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"files_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">3481</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"index_ok"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"db_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">3481</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"synced"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="nt">"integrations"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"tmdb"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"api_key_configured"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"enabled"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"api_reachable"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response Fields</h4>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>status</code></td>
|
|
<td>string</td>
|
|
<td><code>ok</code> if all essential services healthy</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>services</code></td>
|
|
<td>object</td>
|
|
<td>Per-service status (postgres, redis, qdrant)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>services.*.status</code></td>
|
|
<td>string</td>
|
|
<td><code>ok</code>, <code>error</code>, or <code>degraded</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>services.*.latency_ms</code></td>
|
|
<td>int</td>
|
|
<td>Response time in milliseconds</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>resources</code></td>
|
|
<td>object</td>
|
|
<td>CPU, memory usage</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pipeline.scripts_ready</code></td>
|
|
<td>boolean</td>
|
|
<td>Scripts directory accessible</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pipeline.scripts_count</code></td>
|
|
<td>int</td>
|
|
<td>Number of Python processor scripts</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pipeline.processors</code></td>
|
|
<td>object</td>
|
|
<td>Per-processor availability</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pipeline.models_ready</code></td>
|
|
<td>boolean</td>
|
|
<td>Models directory accessible</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>pipeline.scripts_integrity</code></td>
|
|
<td>object</td>
|
|
<td>SHA256 checksum verification results</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>schema.ok</code></td>
|
|
<td>boolean</td>
|
|
<td>All required migrations applied</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>identities.synced</code></td>
|
|
<td>boolean</td>
|
|
<td>Identity file count matches DB count</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>config</code></td>
|
|
<td>object</td>
|
|
<td>Runtime toggle states (cache, auto-pipeline, watcher)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>integrations.tmdb</code></td>
|
|
<td>object</td>
|
|
<td>TMDB API key config and reachability</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h3><code>GET /health/consistency</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: system-level</p>
|
|
<p>Scans the database for data consistency issues. Reports anomalies without modifying any data.</p>
|
|
<h4>Example</h4>
|
|
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/health/consistency"</span><span class="w"> </span>-H<span class="w"> </span><span class="s2">"X-API-Key: </span><span class="nv">$KEY</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'.checks[] | {check, severity, count}'</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response (200)</h4>
|
|
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"degraded"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"checked_at"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-05-18T17:30:00Z"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"checks"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"check"</span><span class="p">:</span><span class="w"> </span><span class="s2">"stale_processing"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"severity"</span><span class="p">:</span><span class="w"> </span><span class="s2">"warn"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"count"</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"files"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span><span class="nt">"file_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"video.mp4"</span><span class="p">,</span><span class="w"> </span><span class="nt">"file_uuid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"abc123..."</span><span class="p">,</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"processing"</span><span class="p">,</span><span class="w"> </span><span class="nt">"detail"</span><span class="p">:</span><span class="w"> </span><span class="s2">"job_id is null"</span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Check</th>
|
|
<th>Description</th>
|
|
<th>Severity</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>stale_processing</code></td>
|
|
<td>Status=processing but job_id is null</td>
|
|
<td><code>warn</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>orphaned_processing</code></td>
|
|
<td>Status=processing but no active monitor_job</td>
|
|
<td><code>warn</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>processing_job_done</code></td>
|
|
<td>Status=processing but job already completed</td>
|
|
<td><code>warn</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unregistered_with_uuid</code></td>
|
|
<td>Status=unregistered but row still in DB (migration residue)</td>
|
|
<td><code>info</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4>Health status rules</h4>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Condition</th>
|
|
<th>status</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>All services ok</td>
|
|
<td><code>ok</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Any service error</td>
|
|
<td><code>degraded</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Postgres or Redis error</td>
|
|
<td><code>degraded</code> (server still responds)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr />
|
|
<h3>Stats Endpoints</h3>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Method</th>
|
|
<th>Endpoint</th>
|
|
<th>Auth</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>GET</td>
|
|
<td><code>/api/v1/stats/sftpgo</code></td>
|
|
<td>No</td>
|
|
<td>SFTPGo service status</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr />
|
|
<p><em>Updated: 2026-05-19 12:49:24</em></p>
|
|
</div>
|
|
</body>
|
|
</html> |