idanoo/GoScrobble
1
0
Fork 0
mirror of https://github.com/idanoo/GoScrobble.git synced 2024-11-21 16:11:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update API docs

Browse Source
This commit is contained in:
Daniel Mason 2021-12-25 17:27:35 +13:00
parent 306bab997b
commit c860b4e2b7
9 changed files with 714 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

470
docs/api/build/index.html
View File

@ -315,11 +315,25 @@
<li> <li>
<a href="#introduction" class="toc-h1 toc-link" data-title="Introduction">Introduction</a> <a href="#introduction" class="toc-h1 toc-link" data-title="Introduction">Introduction</a>
</li> </li>
<li>
<a href="#rate-limits" class="toc-h1 toc-link" data-title="Rate Limits">Rate Limits</a>
</li>
<li> <li>
<a href="#server-info" class="toc-h1 toc-link" data-title="Server Info">Server Info</a> <a href="#server-info" class="toc-h1 toc-link" data-title="Server Info">Server Info</a>
<ul class="toc-list-h2"> <ul class="toc-list-h2">
<li> <li>
<a href="#v1-serverinfo" class="toc-h2 toc-link" data-title="v1/serverinfo">v1/serverinfo</a> <a href="#get-v1-serverinfo" class="toc-h2 toc-link" data-title="GET v1/serverinfo">GET v1/serverinfo</a>
</li>
</ul>
</li>
<li>
<a href="#ingress-endpoints" class="toc-h1 toc-link" data-title="Ingress Endpoints">Ingress Endpoints</a>
<ul class="toc-list-h2">
<li>
<a href="#post-v1-ingress-jellyfin" class="toc-h2 toc-link" data-title="POST v1/ingress/jellyfin">POST v1/ingress/jellyfin</a>
</li>
<li>
<a href="#post-v1-ingress-multiscrobbler" class="toc-h2 toc-link" data-title="POST v1/ingress/multiscrobbler">POST v1/ingress/multiscrobbler</a>
</li> </li>
</ul> </ul>
</li> </li>
@ -327,16 +341,30 @@
<a href="#authentication" class="toc-h1 toc-link" data-title="Authentication">Authentication</a> <a href="#authentication" class="toc-h1 toc-link" data-title="Authentication">Authentication</a>
<ul class="toc-list-h2"> <ul class="toc-list-h2">
<li> <li>
<a href="#v1-login" class="toc-h2 toc-link" data-title="v1/login">v1/login</a> <a href="#post-v1-login" class="toc-h2 toc-link" data-title="POST v1/login">POST v1/login</a>
</li> </li>
<li> <li>
<a href="#v1-register" class="toc-h2 toc-link" data-title="v1/register">v1/register</a> <a href="#post-v1-register" class="toc-h2 toc-link" data-title="POST v1/register">POST v1/register</a>
</li> </li>
<li> <li>
<a href="#v1-sendreset" class="toc-h2 toc-link" data-title="v1/sendreset">v1/sendreset</a> <a href="#post-v1-sendreset" class="toc-h2 toc-link" data-title="POST v1/sendreset">POST v1/sendreset</a>
</li> </li>
<li> <li>
<a href="#v1-resetpassword" class="toc-h2 toc-link" data-title="v1/resetpassword">v1/resetpassword</a> <a href="#post-v1-resetpassword" class="toc-h2 toc-link" data-title="POST v1/resetpassword">POST v1/resetpassword</a>
</li>
<li>
<a href="#post-v1-refresh" class="toc-h2 toc-link" data-title="POST v1/refresh">POST v1/refresh</a>
</li>
</ul>
</li>
<li>
<a href="#admin-endpoints" class="toc-h1 toc-link" data-title="Admin Endpoints">Admin Endpoints</a>
<ul class="toc-list-h2">
<li>
<a href="#get-v1-config" class="toc-h2 toc-link" data-title="GET v1/config">GET v1/config</a>
</li>
<li>
<a href="#post-v1-config" class="toc-h2 toc-link" data-title="POST v1/config">POST v1/config</a>
</li> </li>
</ul> </ul>
</li> </li>
@ -353,8 +381,20 @@
<h1 id='introduction'>Introduction</h1> <h1 id='introduction'>Introduction</h1>
<p>Welcome to the GoScrobble API documentation.</p> <p>Welcome to the GoScrobble API documentation.</p>
<p>The majority of these API endpoints are public with reasonable rate limits.</p> <p>The majority of these API endpoints are public with rate limiting and do not require authentication.</p>
<h1 id='server-info'>Server Info</h1><h2 id='v1-serverinfo'>v1/serverinfo</h2> <h1 id='rate-limits'>Rate Limits</h1>
<p>There are 3 tiers of rate-limiting:<br>
Light rate-limiting: 1 request per 4 seconds with a max burst of 2.<br>
Standard rate-limiting: 5 requests per second with a burst of 5.<br>
Heavy rate-limiting: 10 requests per second with a burst of 10. </p>
<p>The rate limits work as a &#39;bucket&#39; system where there is a max (burst) and a regenerative rate. More info can be found in the source file server_middleware.go.</p>
<p>Each endpoint will depict which rate limit applies.</p>
<p>For example:
On the medium rate-limiter, you start with 5 requests available to you instantly, and this replenishes 5 requests per second.</p>
<h1 id='server-info'>Server Info</h1><h2 id='get-v1-serverinfo'>GET v1/serverinfo</h2>
<blockquote> <blockquote>
<p>Check server version and registration status:</p> <p>Check server version and registration status:</p>
</blockquote> </blockquote>
@ -371,12 +411,299 @@
<p>This endpoint is used to get server API version and registration status.</p> <p>This endpoint is used to get server API version and registration status.</p>
<h3 id='http-request'>HTTP Request</h3> <h3 id='http-request'>HTTP Request</h3>
<p><code>GET https://goscrobble.com/api/v1/serverstatus</code></p> <p><code>GET https://goscrobble.com/api/v1/serverstatus</code></p>
<h1 id='authentication'>Authentication</h1><h2 id='v1-login'>v1/login</h2> <h1 id='ingress-endpoints'>Ingress Endpoints</h1>
<p>Spotify and Navidrome both work on a poll based system and do not require incoming webhooks/endpoints.</p>
<h2 id='post-v1-ingress-jellyfin'>POST v1/ingress/jellyfin</h2>
<blockquote>
<p>Submit a scrobble:</p>
</blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/ingress/jellyfin"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"Name":"&lt;Full JSON structure located in ingress_jellyfin.go&gt;", "Album":"Best Album","Artist":"Best Artist"}'</span>
</code></pre></div>
<blockquote>
<p>Response:</p>
</blockquote>
<div class="highlight"><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="nl">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"success"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div>
<p>Adds a scrobble from Jellyfin into the database. Please view <code>type JellyfinRequest struct</code> in ingress_jellyfin.go for the full request format. You need to install the webhook plugin for this to work.</p>
<aside class="notice">
Light rate-limiting applies
</aside>
<h3 id='http-request'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/ingress/jellyfin</code></p>
<h3 id='query-parameters'>Query Parameters</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>Album</td>
<td>true</td>
<td>string</td>
<td>Album title</td>
</tr>
<tr>
<td>Artist</td>
<td>true</td>
<td>string</td>
<td>Artist name</td>
</tr>
<tr>
<td>Name</td>
<td>true</td>
<td>string</td>
<td>Song title</td>
</tr>
<tr>
<td>ItemType</td>
<td>true</td>
<td>string</td>
<td>Will only scrobble type &#39;Audio&#39;</td>
</tr>
<tr>
<td>ClientName</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>DeviceId</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>DeviceName</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>IsAutomated</td>
<td>false</td>
<td>bool</td>
<td>TBD</td>
</tr>
<tr>
<td>IsPaused</td>
<td>false</td>
<td>bool</td>
<td>TBD</td>
</tr>
<tr>
<td>ItemId</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>MediaSourceId</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>NotificationType</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Overview</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>PlaybackPosition</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>PlaybackPositionTicks</td>
<td>false</td>
<td>int</td>
<td>TBD</td>
</tr>
<tr>
<td>Provider_musicbrainzalbum</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Provider_musicbrainzalbumartist</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Provider_musicbrainzartist</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Provider_musicbrainzreleasegroup</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Provider_musicbrainztrack</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>RunTime</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>RunTimeTicks</td>
<td>false</td>
<td>int</td>
<td>TBD</td>
</tr>
<tr>
<td>ServerId</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>ServerName</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>ServerUrl</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>ServerVersion</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>Timestamp</td>
<td>false</td>
<td>string</td>
<td>TBD</td>
</tr>
<tr>
<td>UserId</td>
<td>false</td>
<td>TBD</td>
<td></td>
</tr>
<tr>
<td>Username</td>
<td>false</td>
<td>TBD</td>
<td></td>
</tr>
<tr>
<td>UtcTimestamp</td>
<td>false</td>
<td>TBD</td>
<td></td>
</tr>
<tr>
<td>Year</td>
<td>false</td>
<td>int</td>
<td>TBD</td>
</tr>
</tbody></table>
<h2 id='post-v1-ingress-multiscrobbler'>POST v1/ingress/multiscrobbler</h2>
<blockquote>
<p>Submit a scrobble:</p>
</blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/ingress/multiscrobbler"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"Track":"&lt;Full JSON structure located in ingress_multiscrobbler.go&gt;", "Album":"Best Album","Artist":["Best Artist1", "Best Artist2"]}'</span>
</code></pre></div>
<blockquote>
<p>Response:</p>
</blockquote>
<div class="highlight"><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="nl">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"success"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div>
<p>Adds a scrobble from MultiScrobbler into the database. Please view <code>type MultiScrobblerRequest struct</code> in ingress_multiscrobbler.go for the full request format.</p>
<aside class="notice">
Light rate-limiting applies
</aside>
<h3 id='http-request-2'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/ingress/multiscrobbler</code></p>
<h3 id='query-parameters-2'>Query Parameters</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>Album</td>
<td>true</td>
<td>string</td>
<td>Album title</td>
</tr>
<tr>
<td>Artist</td>
<td>true</td>
<td>array</td>
<td>Array of Artist names</td>
</tr>
<tr>
<td>Track</td>
<td>true</td>
<td>string</td>
<td>Song title</td>
</tr>
<tr>
<td>PlayedAt</td>
<td>true</td>
<td>int</td>
<td>Unix Timestamp of scrobble time</td>
</tr>
<tr>
<td>Duration</td>
<td>true</td>
<td>int</td>
<td>Song length in seconds</td>
</tr>
</tbody></table>
<h1 id='authentication'>Authentication</h1><h2 id='post-v1-login'>POST v1/login</h2>
<blockquote> <blockquote>
<p>To obtain a JWT token (Replace default credentials):</p> <p>To obtain a JWT token (Replace default credentials):</p>
</blockquote> </blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/login"</span> <span class="se">\</span> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/login"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span> <span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"username":"abc","password":"def"}'</span> <span class="nt">--data</span> <span class="s1">'{"username":"abc","password":"def"}'</span>
</code></pre></div> </code></pre></div>
<blockquote> <blockquote>
@ -387,6 +714,10 @@
</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></code></pre></div> </span></code></pre></div>
<p>This endpoint is used to authenticate and retrieve a JWT token.</p> <p>This endpoint is used to authenticate and retrieve a JWT token.</p>
<aside class="notice">
Standard rate-limiting applies
</aside>
<h3 id='http-request'>HTTP Request</h3> <h3 id='http-request'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/login</code></p> <p><code>POST https://goscrobble.com/api/v1/login</code></p>
<h3 id='query-parameters'>Query Parameters</h3> <h3 id='query-parameters'>Query Parameters</h3>
@ -408,12 +739,13 @@
<td>Account password</td> <td>Account password</td>
</tr> </tr>
</tbody></table> </tbody></table>
<h2 id='v1-register'>v1/register</h2> <h2 id='post-v1-register'>POST v1/register</h2>
<blockquote> <blockquote>
<p>Create a new account (Replace default credentials):</p> <p>Create a new account (Replace default credentials):</p>
</blockquote> </blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/register"</span> <span class="se">\</span> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/register"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span> <span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"email": "test@test.com", "username":"abc","password":"def"}'</span> <span class="nt">--data</span> <span class="s1">'{"email": "test@test.com", "username":"abc","password":"def"}'</span>
</code></pre></div> </code></pre></div>
<blockquote> <blockquote>
@ -424,6 +756,10 @@
</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></code></pre></div> </span></code></pre></div>
<p>If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long.</p> <p>If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long.</p>
<aside class="notice">
Heavy rate-limiting applies
</aside>
<h3 id='http-request-2'>HTTP Request</h3> <h3 id='http-request-2'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/register</code></p> <p><code>POST https://goscrobble.com/api/v1/register</code></p>
<h3 id='query-parameters-2'>Query Parameters</h3> <h3 id='query-parameters-2'>Query Parameters</h3>
@ -450,12 +786,13 @@
<td>Account password</td> <td>Account password</td>
</tr> </tr>
</tbody></table> </tbody></table>
<h2 id='v1-sendreset'>v1/sendreset</h2> <h2 id='post-v1-sendreset'>POST v1/sendreset</h2>
<blockquote> <blockquote>
<p>Trigger a password reset email:</p> <p>Trigger a password reset email:</p>
</blockquote> </blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/sendreset"</span> <span class="se">\</span> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/sendreset"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span> <span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"email":"test@test.com"}'</span> <span class="nt">--data</span> <span class="s1">'{"email":"test@test.com"}'</span>
</code></pre></div> </code></pre></div>
<blockquote> <blockquote>
@ -466,6 +803,10 @@
</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></code></pre></div> </span></code></pre></div>
<p>This endpoint triggers a password reset email to be sent to the email on an account.</p> <p>This endpoint triggers a password reset email to be sent to the email on an account.</p>
<aside class="notice">
Heavy rate-limiting applies
</aside>
<h3 id='http-request-3'>HTTP Request</h3> <h3 id='http-request-3'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/sendreset</code></p> <p><code>POST https://goscrobble.com/api/v1/sendreset</code></p>
<h3 id='query-parameters-3'>Query Parameters</h3> <h3 id='query-parameters-3'>Query Parameters</h3>
@ -482,12 +823,13 @@
<td>Account username</td> <td>Account username</td>
</tr> </tr>
</tbody></table> </tbody></table>
<h2 id='v1-resetpassword'>v1/resetpassword</h2> <h2 id='post-v1-resetpassword'>POST v1/resetpassword</h2>
<blockquote> <blockquote>
<p>Trigger a password reset email:</p> <p>Trigger a password reset email:</p>
</blockquote> </blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/resetpassword"</span> <span class="se">\</span> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/resetpassword"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span> <span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}'</span> <span class="nt">--data</span> <span class="s1">'{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}'</span>
</code></pre></div> </code></pre></div>
<blockquote> <blockquote>
@ -498,6 +840,10 @@
</span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></code></pre></div> </span></code></pre></div>
<p>This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash.</p> <p>This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash.</p>
<aside class="notice">
Heavy rate-limiting applies
</aside>
<h3 id='http-request-4'>HTTP Request</h3> <h3 id='http-request-4'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/resetpassword</code></p> <p><code>POST https://goscrobble.com/api/v1/resetpassword</code></p>
<h3 id='query-parameters-4'>Query Parameters</h3> <h3 id='query-parameters-4'>Query Parameters</h3>
@ -518,6 +864,108 @@
<td>true</td> <td>true</td>
<td>New account password</td> <td>New account password</td>
</tr> </tr>
</tbody></table>
<h2 id='post-v1-refresh'>POST v1/refresh</h2>
<blockquote>
<p>Fetch a new JWT with a refresh token:</p>
</blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/refresh"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"token":"abcdefghijklmnopqrstuvwxyz"}'</span>
</code></pre></div>
<blockquote>
<p>Response:</p>
</blockquote>
<div class="highlight"><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="nl">"token"</span><span class="p">:</span><span class="w"> </span><span class="s2">"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div>
<p>Returns a new JWT token by passing a refresh token.</p>
<aside class="notice">
Standard rate-limiting applies
</aside>
<h3 id='http-request-5'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/refresh</code></p>
<h3 id='query-parameters-5'>Query Parameters</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>token</td>
<td>true</td>
<td>Refresh token from previously issued JWT</td>
</tr>
</tbody></table>
<h1 id='admin-endpoints'>Admin Endpoints</h1>
<aside class="warning">
An admin JWT token is required for the below endpoints
</aside>
<h2 id='get-v1-config'>GET v1/config</h2>
<blockquote>
<p>Fetch configuration values:</p>
</blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/config"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"</span>
</code></pre></div>
<blockquote>
<p>Response:</p>
</blockquote>
<div class="highlight"><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="nl">"SPOTIFY_API_ID"</span><span class="p">:</span><span class="w"> </span><span class="s2">"abc"</span><span class="p">,</span><span class="w">
</span><span class="nl">"SPOTIFY_API_SECRET"</span><span class="p">:</span><span class="w"> </span><span class="s2">"def"</span><span class="p">,</span><span class="w">
</span><span class="nl">"REGISTRATION_ENABLED"</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></code></pre></div>
<p>Fetch instance configuration values.</p>
<aside class="notice">
Standard rate-limiting applies
</aside>
<h3 id='http-request'>HTTP Request</h3>
<p><code>GET https://goscrobble.com/api/v1/config</code></p>
<h2 id='post-v1-config'>POST v1/config</h2>
<blockquote>
<p>Update a configuration parameter:</p>
</blockquote>
<div class="highlight"><pre class="highlight shell tab-shell"><code>curl <span class="s2">"https://goscrobble.com/api/v1/config"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
<span class="nt">-H</span> <span class="s2">"Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"</span> <span class="se">\</span>
<span class="nt">-X</span> POST <span class="se">\</span>
<span class="nt">--data</span> <span class="s1">'{"SPOTIFY_API_ID":"notarealapikey","SPOTIFY_API_SECRET":"notarealsecret"}'</span>
</code></pre></div>
<blockquote>
<p>Response:</p>
</blockquote>
<div class="highlight"><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="nl">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Config updated successfully"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div>
<p>Updates instance configuration values.</p>
<aside class="notice">
Standard rate-limiting applies
</aside>
<h3 id='http-request-2'>HTTP Request</h3>
<p><code>POST https://goscrobble.com/api/v1/config</code></p>
<h3 id='query-parameters'>Query Parameters</h3>
<table><thead>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>key</td>
<td>true</td>
<td>Array of key/value pairs to update. See example.</td>
</tr>
</tbody></table> </tbody></table>
</div> </div>

70
docs/api/source/includes/_admin.md Normal file
View File

@ -0,0 +1,70 @@
# Admin Endpoints
<aside class="warning">
An admin JWT token is required for the below endpoints
</aside>
## GET v1/config
> Fetch configuration values:
```shell
curl "https://goscrobble.com/api/v1/config" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI"
```
> Response:
```json
{
"SPOTIFY_API_ID": "abc",
"SPOTIFY_API_SECRET": "def",
"REGISTRATION_ENABLED": true
}
```
Fetch instance configuration values.
<aside class="notice">
Standard rate-limiting applies
</aside>
### HTTP Request
`GET https://goscrobble.com/api/v1/config`
## POST v1/config
> Update a configuration parameter:
```shell
curl "https://goscrobble.com/api/v1/config" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
-X POST \
--data '{"SPOTIFY_API_ID":"notarealapikey","SPOTIFY_API_SECRET":"notarealsecret"}'
```
> Response:
```json
{
"message": "Config updated successfully"
}
```
Updates instance configuration values.
<aside class="notice">
Standard rate-limiting applies
</aside>
### HTTP Request
`POST https://goscrobble.com/api/v1/config`
### Query Parameters
Parameter | Required | Description
--------- | ------- | -----------
key | true | Array of key/value pairs to update. See example.

62
docs/api/source/includes/_authentication.md
View File

@ -1,12 +1,13 @@
# Authentication # Authentication
## v1/login ## POST v1/login
> To obtain a JWT token (Replace default credentials): > To obtain a JWT token (Replace default credentials):
```shell ```shell
curl "https://goscrobble.com/api/v1/login" \ curl "https://goscrobble.com/api/v1/login" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-X POST \
--data '{"username":"abc","password":"def"}' --data '{"username":"abc","password":"def"}'
``` ```
@ -20,6 +21,10 @@ curl "https://goscrobble.com/api/v1/login" \
This endpoint is used to authenticate and retrieve a JWT token. This endpoint is used to authenticate and retrieve a JWT token.
<aside class="notice">
Standard rate-limiting applies
</aside>
### HTTP Request ### HTTP Request
`POST https://goscrobble.com/api/v1/login` `POST https://goscrobble.com/api/v1/login`
@ -31,13 +36,14 @@ Parameter | Required | Description
username | true | Account username username | true | Account username
password | true | Account password password | true | Account password
## v1/register ## POST v1/register
> Create a new account (Replace default credentials): > Create a new account (Replace default credentials):
```shell ```shell
curl "https://goscrobble.com/api/v1/register" \ curl "https://goscrobble.com/api/v1/register" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-X POST \
--data '{"email": "test@test.com", "username":"abc","password":"def"}' --data '{"email": "test@test.com", "username":"abc","password":"def"}'
``` ```
@ -51,6 +57,10 @@ curl "https://goscrobble.com/api/v1/register" \
If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long. If the server has REGISTRATION_ENABLED=true set, this endpoint will allow you to create a new account. Password must be at least 8 characters long.
<aside class="notice">
Heavy rate-limiting applies
</aside>
### HTTP Request ### HTTP Request
`POST https://goscrobble.com/api/v1/register` `POST https://goscrobble.com/api/v1/register`
@ -63,13 +73,14 @@ email | true | Account email
username | true | Account username username | true | Account username
password | true | Account password password | true | Account password
## v1/sendreset ## POST v1/sendreset
> Trigger a password reset email: > Trigger a password reset email:
```shell ```shell
curl "https://goscrobble.com/api/v1/sendreset" \ curl "https://goscrobble.com/api/v1/sendreset" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-X POST \
--data '{"email":"test@test.com"}' --data '{"email":"test@test.com"}'
``` ```
@ -83,6 +94,10 @@ curl "https://goscrobble.com/api/v1/sendreset" \
This endpoint triggers a password reset email to be sent to the email on an account. This endpoint triggers a password reset email to be sent to the email on an account.
<aside class="notice">
Heavy rate-limiting applies
</aside>
### HTTP Request ### HTTP Request
`POST https://goscrobble.com/api/v1/sendreset` `POST https://goscrobble.com/api/v1/sendreset`
@ -93,13 +108,14 @@ Parameter | Required | Description
--------- | ------- | ----------- --------- | ------- | -----------
email | true | Account username email | true | Account username
## v1/resetpassword ## POST v1/resetpassword
> Trigger a password reset email: > Trigger a password reset email:
```shell ```shell
curl "https://goscrobble.com/api/v1/resetpassword" \ curl "https://goscrobble.com/api/v1/resetpassword" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-X POST \
--data '{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}' --data '{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}'
``` ```
@ -113,6 +129,10 @@ curl "https://goscrobble.com/api/v1/resetpassword" \
This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash. This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash.
<aside class="notice">
Heavy rate-limiting applies
</aside>
### HTTP Request ### HTTP Request
`POST https://goscrobble.com/api/v1/resetpassword` `POST https://goscrobble.com/api/v1/resetpassword`
@ -124,3 +144,37 @@ Parameter | Required | Description
token | true | Reset token from the password reset email token | true | Reset token from the password reset email
password | true | New account password password | true | New account password
## POST v1/refresh
> Fetch a new JWT with a refresh token:
```shell
curl "https://goscrobble.com/api/v1/refresh" \
-H "Content-Type: application/json" \
-X POST \
--data '{"token":"abcdefghijklmnopqrstuvwxyz"}'
```
> Response:
```json
{
"token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g"
}
```
Returns a new JWT token by passing a refresh token.
<aside class="notice">
Standard rate-limiting applies
</aside>
### HTTP Request
`POST https://goscrobble.com/api/v1/refresh`
### Query Parameters
Parameter | Required | Description
--------- | ------- | -----------
token | true | Refresh token from previously issued JWT

22
docs/api/source/includes/_errors.md
View File

@ -1,22 +0,0 @@
# Errors
<aside class="notice">
This error section is stored in a separate file in <code>includes/_errors.md</code>. Slate allows you to optionally separate out your docs into many files...just save them to the <code>includes</code> folder and add them to the top of your <code>index.md</code>'s frontmatter. Files are included in the order listed.
</aside>
The Kittn API uses the following error codes:
Error Code | Meaning
---------- | -------
400 | Bad Request -- Your request is invalid.
401 | Unauthorized -- Your API key is wrong.
403 | Forbidden -- The kitten requested is hidden for administrators only.
404 | Not Found -- The specified kitten could not be found.
405 | Method Not Allowed -- You tried to access a kitten with an invalid method.
406 | Not Acceptable -- You requested a format that isn't json.
410 | Gone -- The kitten requested has been removed from our servers.
418 | I'm a teapot.
429 | Too Many Requests -- You're requesting too many kittens! Slow down!
500 | Internal Server Error -- We had a problem with our server. Try again later.
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

109
docs/api/source/includes/_ingress.md Normal file
View File

@ -0,0 +1,109 @@
# Ingress Endpoints
Spotify and Navidrome both work on a poll based system and do not require incoming webhooks/endpoints.
## POST v1/ingress/jellyfin
> Submit a scrobble:
```shell
curl "https://goscrobble.com/api/v1/ingress/jellyfin" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
-X POST \
--data '{"Name":"<Full JSON structure located in ingress_jellyfin.go>", "Album":"Best Album","Artist":"Best Artist"}'
```
> Response:
```json
{
"message": "success"
}
```
Adds a scrobble from Jellyfin into the database. Please view `type JellyfinRequest struct` in ingress_jellyfin.go for the full request format. You need to install the webhook plugin for this to work.
<aside class="notice">
Light rate-limiting applies
</aside>
### HTTP Request
`POST https://goscrobble.com/api/v1/ingress/jellyfin`
### Query Parameters
Parameter | Required | Type | Description
--------- | ------- | ----------- | -----------
Album | true | string | Album title
Artist | true | string | Artist name
Name | true | string | Song title
ItemType | true | string | Will only scrobble type 'Audio'
ClientName | false | string | TBD
DeviceId | false | string | TBD
DeviceName | false | string | TBD
IsAutomated | false | bool | TBD
IsPaused | false | bool | TBD
ItemId | false | string | TBD
MediaSourceId | false | string | TBD
NotificationType | false | string | TBD
Overview | false | string | TBD
PlaybackPosition | false | string | TBD
PlaybackPositionTicks | false | int | TBD
Provider_musicbrainzalbum | false | string | TBD
Provider_musicbrainzalbumartist | false | string | TBD
Provider_musicbrainzartist | false | string | TBD
Provider_musicbrainzreleasegroup | false | string | TBD
Provider_musicbrainztrack | false | string | TBD
RunTime | false | string | TBD
RunTimeTicks | false | int | TBD
ServerId | false | string | TBD
ServerName | false | string | TBD
ServerUrl | false | string | TBD
ServerVersion | false | string | TBD
Timestamp | false | string | TBD
UserId | false | TBD
Username | false | TBD
UtcTimestamp | false | TBD
Year | false | int | TBD
## POST v1/ingress/multiscrobbler
> Submit a scrobble:
```shell
curl "https://goscrobble.com/api/v1/ingress/multiscrobbler" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" \
-X POST \
--data '{"Track":"<Full JSON structure located in ingress_multiscrobbler.go>", "Album":"Best Album","Artist":["Best Artist1", "Best Artist2"]}'
```
> Response:
```json
{
"message": "success"
}
```
Adds a scrobble from MultiScrobbler into the database. Please view `type MultiScrobblerRequest struct` in ingress_multiscrobbler.go for the full request format.
<aside class="notice">
Light rate-limiting applies
</aside>
### HTTP Request
`POST https://goscrobble.com/api/v1/ingress/multiscrobbler`
### Query Parameters
Parameter | Required | Type | Description
--------- | ------- | ----------- | -----------
Album | true | string | Album title
Artist | true | array | Array of Artist names
Track | true | string | Song title
PlayedAt | true | int | Unix Timestamp of scrobble time
Duration | true | int | Song length in seconds

2
docs/api/source/includes/_introduction.md
View File

@ -2,4 +2,4 @@
Welcome to the GoScrobble API documentation. Welcome to the GoScrobble API documentation.
The majority of these API endpoints are public with reasonable rate limits. The majority of these API endpoints are public with rate limiting and do not require authentication.

13
docs/api/source/includes/_ratelimits.md Normal file
View File

@ -0,0 +1,13 @@
# Rate Limits
There are 3 tiers of rate-limiting:
Light rate-limiting: 1 request per 4 seconds with a max burst of 2.
Standard rate-limiting: 5 requests per second with a burst of 5.
Heavy rate-limiting: 10 requests per second with a burst of 10.
The rate limits work as a 'bucket' system where there is a max (burst) and a regenerative rate. More info can be found in the source file server_middleware.go.
Each endpoint will depict which rate limit applies.
For example:
On the medium rate-limiter, you start with 5 requests available to you instantly, and this replenishes 5 requests per second.

2
docs/api/source/includes/_serverinfo.md
View File

@ -1,5 +1,5 @@
# Server Info # Server Info
## v1/serverinfo ## GET v1/serverinfo
> Check server version and registration status: > Check server version and registration status:
```shell ```shell

3
docs/api/source/index.html.md
View File

@ -11,8 +11,11 @@ toc_footers:
includes: includes:
- introduction - introduction
- ratelimits
- serverinfo - serverinfo
- ingress
- authentication - authentication
- admin
search: true search: true