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.
+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.
+@@ -371,12 +411,299 @@Check server version and registration status:
This endpoint is used to get server API version and registration status.
GET https://goscrobble.com/api/v1/serverstatus
Spotify and Navidrome both work on a poll based system and do not require incoming webhooks/endpoints.
+++Submit a scrobble:
+
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:
+
{
+ "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.
POST https://goscrobble.com/api/v1/ingress/jellyfin
| 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 | +
++Submit a scrobble:
+
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:
+
{
+ "message": "success"
+}
+Adds a scrobble from MultiScrobbler into the database. Please view type MultiScrobblerRequest struct in ingress_multiscrobbler.go for the full request format.
POST https://goscrobble.com/api/v1/ingress/multiscrobbler
| 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 | +
To obtain a JWT token (Replace default credentials):
curl "https://goscrobble.com/api/v1/login" \
-H "Content-Type: application/json" \
+ -X POST \
--data '{"username":"abc","password":"def"}'
@@ -387,6 +714,10 @@ }This endpoint is used to authenticate and retrieve a JWT token.
+ +HTTP Request
POST https://goscrobble.com/api/v1/loginQuery Parameters
@@ -408,12 +739,13 @@Account password -v1/register
+POST v1/register
Create a new account (Replace default credentials):
curl "https://goscrobble.com/api/v1/register" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"email": "test@test.com", "username":"abc","password":"def"}'@@ -424,6 +756,10 @@ }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.
+ +HTTP Request
POST https://goscrobble.com/api/v1/registerQuery Parameters
@@ -450,12 +786,13 @@Account password -v1/sendreset
+POST v1/sendreset
Trigger a password reset email:
curl "https://goscrobble.com/api/v1/sendreset" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"email":"test@test.com"}'@@ -466,6 +803,10 @@ }This endpoint triggers a password reset email to be sent to the email on an account.
+ +HTTP Request
POST https://goscrobble.com/api/v1/sendresetQuery Parameters
@@ -482,12 +823,13 @@Account username -v1/resetpassword
+POST v1/resetpassword
Trigger a password reset email:
curl "https://goscrobble.com/api/v1/resetpassword" \ -H "Content-Type: application/json" \ + -X POST \ --data '{"token":"abcdefghijklmnopqrstuvwxyz", "password": "Hunter1"}'@@ -498,6 +840,10 @@ }This endpoint confirms a password reset with a valid hash from the reset email. You must call v1/sendreset first and obtain the hash.
+ +HTTP Request
POST https://goscrobble.com/api/v1/resetpasswordQuery Parameters
@@ -518,6 +864,108 @@true New account password + +POST v1/refresh
+++Fetch a new JWT with a refresh token:
++curl "https://goscrobble.com/api/v1/refresh" \ + -H "Content-Type: application/json" \ + -X POST \ + --data '{"token":"abcdefghijklmnopqrstuvwxyz"}' +++Response:
++{ + "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g" +} +Returns a new JWT token by passing a refresh token.
+ + +HTTP Request
++
POST https://goscrobble.com/api/v1/refreshQuery Parameters
++
++ + +Parameter +Required +Description ++ +token +true +Refresh token from previously issued JWT +Admin Endpoints
+ +GET v1/config
+++Fetch configuration values:
++curl "https://goscrobble.com/api/v1/config" \ + -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsI" +++Response:
++{ + "SPOTIFY_API_ID": "abc", + "SPOTIFY_API_SECRET": "def", + "REGISTRATION_ENABLED": true +} +Fetch instance configuration values.
+ + +HTTP Request
++
GET https://goscrobble.com/api/v1/configPOST v1/config
+++Update a configuration parameter:
++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:
++{ + "message": "Config updated successfully" +} +Updates instance configuration values.
+ + +HTTP Request
++
POST https://goscrobble.com/api/v1/configQuery Parameters
++
diff --git a/docs/api/source/includes/_admin.md b/docs/api/source/includes/_admin.md new file mode 100644 index 00000000..f393328b --- /dev/null +++ b/docs/api/source/includes/_admin.md @@ -0,0 +1,70 @@ +# Admin Endpoints + + +## 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. + + + +### 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. + + + +### 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. \ No newline at end of file diff --git a/docs/api/source/includes/_authentication.md b/docs/api/source/includes/_authentication.md index c74bd382..95ff0ac9 100644 --- a/docs/api/source/includes/_authentication.md +++ b/docs/api/source/includes/_authentication.md @@ -1,12 +1,13 @@ # Authentication -## v1/login +## POST v1/login > To obtain a JWT token (Replace default credentials): ```shell curl "https://goscrobble.com/api/v1/login" \ -H "Content-Type: application/json" \ + -X POST \ --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. + + ### HTTP Request `POST https://goscrobble.com/api/v1/login` @@ -31,13 +36,14 @@ Parameter | Required | Description username | true | Account username password | true | Account password -## v1/register +## POST v1/register > Create a new account (Replace default credentials): ```shell curl "https://goscrobble.com/api/v1/register" \ -H "Content-Type: application/json" \ + -X POST \ --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. + + ### HTTP Request `POST https://goscrobble.com/api/v1/register` @@ -63,13 +73,14 @@ email | true | Account email username | true | Account username password | true | Account password -## v1/sendreset +## POST v1/sendreset > Trigger a password reset email: ```shell curl "https://goscrobble.com/api/v1/sendreset" \ -H "Content-Type: application/json" \ + -X POST \ --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. + + ### HTTP Request `POST https://goscrobble.com/api/v1/sendreset` @@ -93,13 +108,14 @@ Parameter | Required | Description --------- | ------- | ----------- email | true | Account username -## v1/resetpassword +## POST v1/resetpassword > Trigger a password reset email: ```shell curl "https://goscrobble.com/api/v1/resetpassword" \ -H "Content-Type: application/json" \ + -X POST \ --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. + + ### HTTP Request `POST https://goscrobble.com/api/v1/resetpassword` @@ -124,3 +144,37 @@ Parameter | Required | Description token | true | Reset token from the password reset email 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. + + + +### HTTP Request + +`POST https://goscrobble.com/api/v1/refresh` + +### Query Parameters + +Parameter | Required | Description +--------- | ------- | ----------- +token | true | Refresh token from previously issued JWT diff --git a/docs/api/source/includes/_errors.md b/docs/api/source/includes/_errors.md deleted file mode 100644 index 7b35e92b..00000000 --- a/docs/api/source/includes/_errors.md +++ /dev/null @@ -1,22 +0,0 @@ -# Errors - - - -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. diff --git a/docs/api/source/includes/_ingress.md b/docs/api/source/includes/_ingress.md new file mode 100644 index 00000000..31f80120 --- /dev/null +++ b/docs/api/source/includes/_ingress.md @@ -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":"+ + +Parameter +Required +Description ++ key +true +Array of key/value pairs to update. See example. +", "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. + + + +### 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":" ", "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. + + + +### 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 \ No newline at end of file diff --git a/docs/api/source/includes/_introduction.md b/docs/api/source/includes/_introduction.md index 19b4193f..9fbfa96e 100644 --- a/docs/api/source/includes/_introduction.md +++ b/docs/api/source/includes/_introduction.md @@ -2,4 +2,4 @@ Welcome to the GoScrobble API documentation. -The majority of these API endpoints are public with reasonable rate limits. \ No newline at end of file +The majority of these API endpoints are public with rate limiting and do not require authentication. \ No newline at end of file diff --git a/docs/api/source/includes/_ratelimits.md b/docs/api/source/includes/_ratelimits.md new file mode 100644 index 00000000..0b068a57 --- /dev/null +++ b/docs/api/source/includes/_ratelimits.md @@ -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. diff --git a/docs/api/source/includes/_serverinfo.md b/docs/api/source/includes/_serverinfo.md index ede2c636..631afd65 100644 --- a/docs/api/source/includes/_serverinfo.md +++ b/docs/api/source/includes/_serverinfo.md @@ -1,5 +1,5 @@ # Server Info -## v1/serverinfo +## GET v1/serverinfo > Check server version and registration status: ```shell diff --git a/docs/api/source/index.html.md b/docs/api/source/index.html.md index daf59bd0..b558cc8e 100644 --- a/docs/api/source/index.html.md +++ b/docs/api/source/index.html.md @@ -11,8 +11,11 @@ toc_footers: includes: - introduction + - ratelimits - serverinfo + - ingress - authentication + - admin search: true