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.

Base URL for the API endpoints: https://goscrobble.com/api

# 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`

# Administration

An admin JWT token is required for the below 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.

Standard rate-limiting applies

### 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.

Standard rate-limiting applies

### 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.

# 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.

Standard rate-limiting applies

### 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.

Heavy rate-limiting applies

### 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.

Heavy rate-limiting applies

### 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.

Heavy rate-limiting applies

### 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.

Standard rate-limiting applies

### HTTP Request

`POST https://goscrobble.com/api/v1/refresh`

### Query Parameters

Parameter | Required | Description
--- | --- | ---
token | true | Refresh token from previously issued JWT

# 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.

Light rate-limiting applies

### 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.

Light rate-limiting applies

### 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

shell