NAV
shell

Introduction

Welcome to the GoScrobble API documentation.

The majority of these API endpoints are public with rate limiting and do not require authentication.

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.

Server Info

GET v1/serverinfo

Check server version and registration status:

curl "https://goscrobble.com/api/v1/serverinfo"

Response:

{
  "version":"0.1.1",
  "registration_enabled":"1"
}

This endpoint is used to get server API version and registration status.

HTTP Request

GET https://goscrobble.com/api/v1/serverstatus

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:

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.

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:

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.

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

Authentication

POST v1/login

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"}'

Response:

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhZG1pbiI6ZmFsc2UsImVtYWlsIjoidGVzdEB0ZXN0LmNvbSIsImV4cCI6MTY0MTAwMjUxOSwiaWF0IjoxNjQwMzk3NzE5LCJtb2QiOnRydWUsInJlZnJlc2hfZXhwIjoxNjQxMDAyNTE5LCJyZWZyZXNoX3Rva2VuIjoiYWJjZGVmZ2hqaWtsbW5vcHF3ZXJ0dXZ3eHl6Iiwic3ViIjoiNDE4ZmRkZmItOGIxYi01MWFiLTliZHMtNGZnMDhjYTYzY2ZmIiwidXNlcm5hbWUiOiJ0ZXN0In0.fuPXjQ7IzNyttgIKpdS4-KBQ-QeHTl-BfgYkSnMCmpVrBunzMrSwr1RzxI7Xg2WWF-FHtW3Bnv9RpSqLDN4F2g"
}

This endpoint is used to authenticate and retrieve a JWT token.

HTTP Request

POST https://goscrobble.com/api/v1/login

Query Parameters

Parameter Required Description
username true Account username
password true Account password

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"}'

Response:

{
  "message": "User created succesfully. You may now login"
}

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

Query Parameters

Parameter Required Description
email true Account email
username true Account username
password true Account password

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"}'

Response:

{
  "message": "Password reset email sent"
}

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

Query Parameters

Parameter Required Description
email true Account username

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"}'

Response:

{
  "message": "Password updated successfully!"
}

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

Query Parameters

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:

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/refresh

Query 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/config

POST 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/config

Query Parameters

Parameter Required Description
key true Array of key/value pairs to update. See example.
shell