Songlist API
Version: 2.0.0
Export
/songsGet songs
Authorization
Requires a valid access token (no specific scope)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| attributes | query | integer[] | No | The attributes to filter by |
| search | query | string | No | Filter by title and/or artist |
| is_new | query | boolean | No | Only return songs that are new |
| order_by | query | string titleartistlastPlayedtimesPlayedduration | No | The column to sort by |
| order_dir | query | string ascdesc | No | The direction to sort by |
| last_played_before | query | string | No | Filter to songs last played before this date (RFC3339). Includes never-played songs. |
| last_played_after | query | string | No | Filter to songs last played after this date (RFC3339). Excludes never-played songs. |
| times_played_op | query | string eqltltegtgte | No | Comparison operator for times played filter |
| times_played_value | query | integer | No | Value to compare times played against |
| duration_min | query | integer | No | Only return songs at least this many seconds long. Songs with no recorded duration are excluded. |
| duration_max | query | integer | No | Only return songs at most this many seconds long. Songs with no recorded duration are excluded. |
| in_queue | query | string allexcludeonly | No | Filter by queue status |
| favorites | query | string only | No | Filter to only the authenticated user's favorited songs |
| collab | query | string only | No | Filter to songs every accepted collab guest also has (no-op without an active collab session) |
| limit | query | integer | No | The number of recrords to return |
| after | query | string | No | The cursor to start from |
| streamer_id | query | string | No | If not provided, 'streamer_name' and 'platform' are required |
| streamer_name | query | string | No | Required if streamer_id is not supplied |
| platform_id | query | string | No | Platform-specific channel ID. Requires 'platform' |
| platform | query | string kicknonetwitchyoutube | No | Required if streamer_name or platform_id is supplied |
Responses
200OK
application/json
Schema
SongsResponseBody
A URL to the JSON Schema for this object.
Array items:
SongSummary
Array items:
SongAttribute
Example
{
"$schema": "https://example.com",
"items": [
{
"active": true,
"albumArt": "string",
"artist": "string",
"attributes": [
{
"id": 0,
"image": "string",
"name": "string"
}
],
"bypassRequestLimits": true,
"capo": "string",
"comment": "string",
"createdAt": "2024-01-01T00:00:00Z",
"durationSeconds": 0,
"favorite": true,
"id": 0,
"inCollab": true,
"isNew": true,
"lastActivation": "2024-01-01T00:00:00Z",
"lastPlayed": "2024-01-01T00:00:00Z",
"lastPlayedFrom": "string",
"learnListId": "string",
"masterSongId": 0,
"minAmount": 0,
"minTokens": 0,
"numQueued": 0,
"streamerId": 0,
"timesPlayed": 0,
"title": "string"
}
],
"token": "string",
"total": 0
}400Bad Request
application/problem+json
Schema
ErrorModel
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
Array items:
ErrorDetail
Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{
"$schema": "https://example.com",
"detail": "string",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com",
"status": 0,
"title": "string",
"type": "about:blank"
}401Unauthorized
application/problem+json
Schema
ErrorModel
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
Array items:
ErrorDetail
Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{
"$schema": "https://example.com",
"detail": "string",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com",
"status": 0,
"title": "string",
"type": "about:blank"
}403Forbidden
application/problem+json
Schema
ErrorModel
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
Array items:
ErrorDetail
Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{
"$schema": "https://example.com",
"detail": "string",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com",
"status": 0,
"title": "string",
"type": "about:blank"
}422Unprocessable Entity
application/problem+json
Schema
ErrorModel
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
Array items:
ErrorDetail
Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{
"$schema": "https://example.com",
"detail": "string",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com",
"status": 0,
"title": "string",
"type": "about:blank"
}500Internal Server Error
application/problem+json
Schema
ErrorModel
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
Array items:
ErrorDetail
Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{
"$schema": "https://example.com",
"detail": "string",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com",
"status": 0,
"title": "string",
"type": "about:blank"
}