Deployed 84d9b92 with MkDocs version: 1.6.1

This commit is contained in:
2026-07-07 04:51:21 +00:00
parent 6dcc804d48
commit 7a802311e3
26 changed files with 952 additions and 362 deletions
+3 -3
View File
@@ -2185,7 +2185,7 @@
</span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">alice</span>
</span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="w"> </span><span class="nt">devices</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;my_widevine_device&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># Widevine (.wvd) devices this key may use</span>
</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="w"> </span><span class="nt">playready_devices</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;my_playready_prd&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># PlayReady (.prd) devices this key may use</span>
</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;AMZN&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;NF&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># optional per-key service allowlist</span>
</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;EXAMPLE1&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;EXAMPLE2&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># optional per-key service allowlist</span>
</span><span id="__span-3-9"><a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a><span class="w"> </span><span class="nt">a-secret-key-for-bob</span><span class="p">:</span>
</span><span id="__span-3-10"><a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bob</span>
</span><span id="__span-3-11"><a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a><span class="w"> </span><span class="nt">devices</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;my_widevine_device&quot;</span><span class="p p-Indicator">]</span>
@@ -2353,11 +2353,11 @@
</table>
<div class="language-yaml highlight"><span class="filename">Restricting services</span><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="nt">serve</span><span class="p">:</span>
</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="w"> </span><span class="nt">api_secret</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;admin-key&quot;</span>
</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;AMZN&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;NF&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;DSNP&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># global ceiling for all keys</span>
</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;EXAMPLE1&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;EXAMPLE2&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;EXAMPLE3&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># global ceiling for all keys</span>
</span><span id="__span-13-4"><a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a><span class="w"> </span><span class="nt">users</span><span class="p">:</span>
</span><span id="__span-13-5"><a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a><span class="w"> </span><span class="nt">limited-key</span><span class="p">:</span>
</span><span id="__span-13-6"><a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-6"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">limited</span>
</span><span id="__span-13-7"><a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;AMZN&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># this key ends up allowed only AMZN</span>
</span><span id="__span-13-7"><a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;EXAMPLE1&quot;</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># this key ends up allowed only EXAMPLE1</span>
</span></code></pre></div>
<p>Endpoints that name a service (listing services, searching, listing titles/tracks, downloading, profiles, history, and remote sessions) all filter against this allowlist. A request for a service outside the key's allowlist is rejected as an invalid service. Service tags are matched after normalization, so casing and aliases resolve consistently.</p>
<h3 id="cdm-overrides-and-per-job-credentials">CDM overrides and per-job credentials<a class="headerlink" href="#cdm-overrides-and-per-job-credentials" title="Permanent link">&para;</a></h3>
+26 -26
View File
@@ -2744,14 +2744,14 @@
<td><code>service</code></td>
<td>string</td>
<td>yes</td>
<td>—</td>
<td>-</td>
<td>Service tag.</td>
</tr>
<tr>
<td><code>query</code></td>
<td>string</td>
<td>yes</td>
<td>—</td>
<td>-</td>
<td>Search query.</td>
</tr>
<tr>
@@ -2814,7 +2814,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Search completed.</td>
</tr>
<tr>
@@ -2934,7 +2934,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Titles returned.</td>
</tr>
<tr>
@@ -3009,7 +3009,7 @@
</tr>
<tr>
<td><code>profile</code>, <code>proxy</code>, <code>no_proxy</code>, <code>cdm_type</code></td>
<td>—</td>
<td>-</td>
<td>no</td>
<td>As on <code>list-titles</code>.</td>
</tr>
@@ -3074,7 +3074,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Tracks returned.</td>
</tr>
<tr>
@@ -3339,7 +3339,7 @@
</tr>
<tr>
<td><code>tmdb_id</code> / <code>imdb_id</code> / <code>animeapi_id</code></td>
<td>—</td>
<td>-</td>
<td><code>null</code></td>
<td>External ID overrides for tagging.</td>
</tr>
@@ -3384,7 +3384,7 @@
<tbody>
<tr>
<td><code>202</code></td>
<td>—</td>
<td>-</td>
<td>Job queued.</td>
</tr>
<tr>
@@ -3425,13 +3425,13 @@
<tr>
<td><code>status</code></td>
<td><code>queued</code>, <code>downloading</code>, <code>completed</code>, <code>failed</code>, <code>cancelled</code></td>
<td>—</td>
<td>-</td>
<td>Filter by status.</td>
</tr>
<tr>
<td><code>service</code></td>
<td>service tag</td>
<td>—</td>
<td>-</td>
<td>Filter by service.</td>
</tr>
<tr>
@@ -3501,7 +3501,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Jobs returned.</td>
</tr>
<tr>
@@ -3524,7 +3524,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Job returned.</td>
</tr>
<tr>
@@ -3555,12 +3555,12 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Job cancelled.</td>
</tr>
<tr>
<td><code>204</code></td>
<td>—</td>
<td>-</td>
<td>Terminal job removed (empty body).</td>
</tr>
<tr>
@@ -3614,7 +3614,7 @@
<tbody>
<tr>
<td><code>202</code></td>
<td>—</td>
<td>-</td>
<td>New job queued.</td>
</tr>
<tr>
@@ -3660,7 +3660,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Job moved to front.</td>
</tr>
<tr>
@@ -3744,7 +3744,7 @@
<tr>
<td><code>service</code></td>
<td>string</td>
<td>—</td>
<td>-</td>
<td>Case-insensitive service filter.</td>
</tr>
</tbody>
@@ -3784,7 +3784,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>History returned.</td>
</tr>
<tr>
@@ -3807,7 +3807,7 @@
<tbody>
<tr>
<td><code>204</code></td>
<td>—</td>
<td>-</td>
<td>Entry removed (empty body).</td>
</tr>
<tr>
@@ -3843,7 +3843,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Directory cleared.</td>
</tr>
<tr>
@@ -3924,7 +3924,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Session created; authentication in progress.</td>
</tr>
<tr>
@@ -3972,7 +3972,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Status returned.</td>
</tr>
<tr>
@@ -4008,7 +4008,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Response accepted.</td>
</tr>
<tr>
@@ -4069,7 +4069,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Tracks returned.</td>
</tr>
<tr>
@@ -4109,7 +4109,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>Segment info returned.</td>
</tr>
<tr>
@@ -4193,7 +4193,7 @@
<tbody>
<tr>
<td><code>200</code></td>
<td>—</td>
<td>-</td>
<td>License/keys returned.</td>
</tr>
<tr>
+1 -1
View File
@@ -2213,7 +2213,7 @@ The classification is keyword-based, checked in order:</p>
<table>
<thead>
<tr>
<th>If the error mentions…</th>
<th>If the error mentions...</th>
<th>It becomes</th>
<th>Retryable</th>
</tr>
+1 -1
View File
@@ -2169,7 +2169,7 @@ every request except <code>/api/health</code>:</p>
<div class="language-shell highlight"><span class="filename">An authenticated request</span><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>curl<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span>http://127.0.0.1:8786/api/search<span class="w"> </span><span class="se">\</span>
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">&quot;X-Secret-Key: your-api-secret&quot;</span><span class="w"> </span><span class="se">\</span>
</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">&quot;Content-Type: application/json&quot;</span><span class="w"> </span><span class="se">\</span>
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w"> </span>-d<span class="w"> </span><span class="s1">&#39;{&quot;service&quot;: &quot;NF&quot;, &quot;query&quot;: &quot;example&quot;}&#39;</span>
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w"> </span>-d<span class="w"> </span><span class="s1">&#39;{&quot;service&quot;: &quot;EXAMPLE&quot;, &quot;query&quot;: &quot;example&quot;}&#39;</span>
</span></code></pre></div>
<p>A missing or unknown key returns <code>401</code>. The full model, including per-key service
allowlists, is covered in <a href="authentication/">Authentication</a>.</p>
+2 -2
View File
@@ -2248,7 +2248,7 @@ replies with <strong><code>202 Accepted</code></strong> and the new job's identi
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">&quot;X-Secret-Key: your-api-secret&quot;</span><span class="w"> </span><span class="se">\</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w"> </span>-H<span class="w"> </span><span class="s2">&quot;Content-Type: application/json&quot;</span><span class="w"> </span><span class="se">\</span>
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="w"> </span>-d<span class="w"> </span><span class="s1">&#39;{</span>
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="s1"> &quot;service&quot;: &quot;NF&quot;,</span>
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="s1"> &quot;service&quot;: &quot;EXAMPLE&quot;,</span>
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="s1"> &quot;title_id&quot;: &quot;81234567&quot;,</span>
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="s1"> &quot;quality&quot;: [&quot;1080&quot;],</span>
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="s1"> &quot;range&quot;: [&quot;HDR10&quot;]</span>
@@ -2445,7 +2445,7 @@ state, and this is important because the response differs:</p>
</tr>
<tr>
<td>Not found</td>
<td>—</td>
<td>-</td>
<td><code>404</code> with error code <code>JOB_NOT_FOUND</code></td>
</tr>
</tbody>
+3 -3
View File
@@ -2112,7 +2112,7 @@
</span></code></pre></div>
<div class="admonition warning">
<p class="admonition-title">Two error shapes exist</p>
<p>The authentication middleware returns the short <code>{"status": 401, "message": "..."}</code> shape shown above. Every <strong>other</strong> error the API produces uses the richer structured shape (<code>error_code</code>, <code>timestamp</code>, <code>details</code>, …) described in <a href="#error-handling">Error handling</a>. A robust client should handle both.</p>
<p>The authentication middleware returns the short <code>{"status": 401, "message": "..."}</code> shape shown above. Every <strong>other</strong> error the API produces uses the richer structured shape (<code>error_code</code>, <code>timestamp</code>, <code>details</code>, ...) described in <a href="#error-handling">Error handling</a>. A robust client should handle both.</p>
</div>
<p>The <code>tag</code> value for the service you want is the identifier you pass as <code>service</code> in the calls below.</p>
<hr />
@@ -2167,12 +2167,12 @@
<tbody>
<tr>
<td><code>service</code></td>
<td>—</td>
<td>-</td>
<td>Service tag (required)</td>
</tr>
<tr>
<td><code>title_id</code></td>
<td>—</td>
<td>-</td>
<td>Title identifier (required)</td>
</tr>
<tr>
+12 -12
View File
@@ -2108,7 +2108,7 @@ entry names a server and provides its URL and API key.</p>
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="w"> </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="w"> </span><span class="c1"># Optional: per-service config overrides applied locally (title_map, cdm, etc.)</span>
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span>
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="w"> </span><span class="nt">AMZN</span><span class="p">:</span>
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="w"> </span><span class="nt">EXAMPLE</span><span class="p">:</span>
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="w"> </span><span class="nt">title_map</span><span class="p">:</span>
</span><span id="__span-1-11"><a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a><span class="w"> </span><span class="s">&quot;0ABCDEF&quot;</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="s">&quot;The</span><span class="nv"> </span><span class="s">Show</span><span class="nv"> </span><span class="s">(Renamed</span><span class="nv"> </span><span class="s">Locally)&quot;</span>
</span></code></pre></div>
@@ -2151,10 +2151,10 @@ not the default.</p>
</div>
<h3 id="selecting-a-server">Selecting a server<a class="headerlink" href="#selecting-a-server" title="Permanent link">&para;</a></h3>
<p>If exactly one server is configured, unshackle uses it implicitly:</p>
<div class="language-bash highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>AMZN<span class="w"> </span>0ABCDEF
<div class="language-bash highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>EXAMPLE<span class="w"> </span>0ABCDEF
</span></code></pre></div>
<p>If <strong>more than one</strong> server is configured, you must pick one with <code>--server</code>:</p>
<div class="language-bash highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--server<span class="w"> </span>my_server<span class="w"> </span>AMZN<span class="w"> </span>0ABCDEF
<div class="language-bash highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--server<span class="w"> </span>my_server<span class="w"> </span>EXAMPLE<span class="w"> </span>0ABCDEF
</span></code></pre></div>
<p>With no <code>remote_services</code> configured at all, unshackle raises a clear error telling
you to add the block shown above.</p>
@@ -2390,9 +2390,9 @@ from a browser origin, not when you simply want the local HTTP API.</p>
<code>quality</code>, <code>best_available</code>, plus arbitrary service CLI options
(<code>additionalProperties: true</code>).</p>
<p>The response returns <strong>before</strong> authentication finishes:</p>
<div class="language-json highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;session_id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;…uuid4…&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;service&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;AMZN&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;authenticating&quot;</span><span class="w"> </span><span class="p">}</span>
<div class="language-json highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;session_id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...uuid4...&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;service&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;EXAMPLE&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;authenticating&quot;</span><span class="w"> </span><span class="p">}</span>
</span></code></pre></div>
<p>Authentication runs on a background thread (<code>asyncio.to_thread(authenticate, …)</code>).
<p>Authentication runs on a background thread (<code>asyncio.to_thread(authenticate, ...)</code>).
The session starts in <code>AUTHENTICATING</code>; the client must poll the prompt endpoint
until it reaches <code>authenticated</code> (or <code>failed</code>).</p>
<h3 id="interactive-auth-the-inputbridge">Interactive auth: the <code>InputBridge</code><a class="headerlink" href="#interactive-auth-the-inputbridge" title="Permanent link">&para;</a></h3>
@@ -2411,10 +2411,10 @@ layer.</p>
<div class="language-json highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;authenticated&quot;</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;authenticating&quot;</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-7-3"><a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;pending_input&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;prompt&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;Enter code: &quot;</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-7-4"><a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;failed&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;error&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;…message…&quot;</span><span class="w"> </span><span class="p">}</span>
</span><span id="__span-7-4"><a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;failed&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;error&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...message...&quot;</span><span class="w"> </span><span class="p">}</span>
</span></code></pre></div>
<p>A missing session returns <code>404 SESSION_NOT_FOUND</code>; an IP mismatch returns
<code>403 FORBIDDEN</code>. <code>POST /api/session/{id}/prompt</code> takes <code>{ "response": "…" }</code> and
<code>403 FORBIDDEN</code>. <code>POST /api/session/{id}/prompt</code> takes <code>{ "response": "..." }</code> and
returns <code>{ "status": "accepted" }</code>; posting with no pending prompt is an
<code>INVALID_INPUT</code> error.</p>
<h3 id="sessionstore-internals"><code>SessionStore</code> internals<a class="headerlink" href="#sessionstore-internals" title="Permanent link">&para;</a></h3>
@@ -2496,13 +2496,13 @@ returns <code>{ "status": "accepted" }</code>; posting with no pending prompt is
On <code>DELETE</code>, the handler harvests updated cache files (compressing each with zlib
and base64-encoding, <strong>excluding</strong> <code>titles_*</code> files) and returns them under a
<code>cache</code> key so the client can persist refreshed tokens:</p>
<div class="language-json highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;cache&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">&quot;tokens&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;…base64(zlib(bytes))…&quot;</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
<div class="language-json highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;ok&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;cache&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">&quot;tokens&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...base64(zlib(bytes))...&quot;</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
</span></code></pre></div>
<h3 id="session-info-response">Session info response<a class="headerlink" href="#session-info-response" title="Permanent link">&para;</a></h3>
<p><code>GET /api/session/{id}</code>:</p>
<div class="language-json highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="p">{</span>
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w"> </span><span class="nt">&quot;session_id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;…&quot;</span><span class="p">,</span>
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w"> </span><span class="nt">&quot;service&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;AMZN&quot;</span><span class="p">,</span>
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w"> </span><span class="nt">&quot;session_id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;...&quot;</span><span class="p">,</span>
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w"> </span><span class="nt">&quot;service&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;EXAMPLE&quot;</span><span class="p">,</span>
</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w"> </span><span class="nt">&quot;valid&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w"> </span><span class="nt">&quot;expires_in&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">300</span><span class="p">,</span>
</span><span id="__span-10-6"><a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w"> </span><span class="nt">&quot;track_count&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">12</span><span class="p">,</span>
@@ -2536,7 +2536,7 @@ session API and a good template for any client.</p>
<hr />
<h2 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">&para;</a></h2>
<div class="admonition example">
<p class="admonition-title">\"Could not connect to remote server … Is it running?\"</p>
<p class="admonition-title">\"Could not connect to remote server ... Is it running?\"</p>
<p>The client couldn't reach the URL. Confirm <code>unshackle serve</code> is running on the
server, the <code>url</code>/port in <code>remote_services</code> are correct (default port <code>8786</code>),
and any firewall or reverse proxy allows the connection.</p>
@@ -2555,7 +2555,7 @@ prompts you, check that credentials/cookies forwarded from the client are valid
for the service.</p>
</div>
<div class="admonition example">
<p class="admonition-title">\"Multiple remote services configured. Use --server …\"</p>
<p class="admonition-title">\"Multiple remote services configured. Use --server ...\"</p>
<p>You have more than one entry under <code>remote_services</code>. Pass <code>--server &lt;name&gt;</code>
to pick one.</p>
</div>