Songlist API

Version: 2.0.0

Export

Download

Copy URL

post/songs/bulk-update-filtered

Set the active state on every song matching the given filters

Sets the active state on every song matching the supplied filters. With no filters set this updates the streamer's entire songlist. Songs already in the target state are not counted.

Authorization

Required scopes

streamer.song.writeWrite streamer songs

Request Bodyrequired

application/json

Schema

UpdateAllSongsParamsBody

$schemastring

A URL to the JSON Schema for this object.

activestring

Only update songs with this active state (omit for both)

truefalse

attributesinteger[]

Only update songs carrying every one of these attributes

Array items:

integer (int32)

collabstring

Only update songs every accepted collab guest also has

only

durationMaxinteger

Only update songs at most this many seconds long. Songs with no recorded duration are excluded.

durationMininteger

Only update songs at least this many seconds long. Songs with no recorded duration are excluded.

favoritesstring

Only update the authenticated user's favorited songs

only

inQueuestring

Only update songs with this queue status

allexcludeonly

isNewboolean

Only update songs that are new

lastPlayedAfterstring

Only update songs last played after this date (RFC3339). Excludes never-played songs.

lastPlayedBeforestring

Only update songs last played before this date (RFC3339). Includes never-played songs.

searchstring

Only update songs matching this title/artist search

setActivebooleanrequired

Active state to set on every matching song

streamerIdintegerrequired

The streamer's ID. Can be found using the GET /streamers endpoint with the streamer_name and platform parameters

timesPlayedOpstring

Comparison operator for the times played filter

eqltltegtgte

timesPlayedValueinteger

Value to compare times played against

Example

{
  "$schema": "https://example.com",
  "active": "true",
  "attributes": [
    0
  ],
  "collab": "only",
  "durationMax": 0,
  "durationMin": 0,
  "favorites": "only",
  "inQueue": "all",
  "isNew": true,
  "lastPlayedAfter": "2024-01-01T00:00:00Z",
  "lastPlayedBefore": "2024-01-01T00:00:00Z",
  "search": "string",
  "setActive": true,
  "streamerId": 1,
  "timesPlayedOp": "eq",
  "timesPlayedValue": 0
}

Responses

200OK

application/json

Schema

UpdateAllSongsResponseBody

$schemastring

A URL to the JSON Schema for this object.

updatedCountintegerrequired

Example

{
  "$schema": "https://example.com",
  "updatedCount": 0
}

400Bad Request

application/problem+json

Schema

ErrorModel

$schemastring

A URL to the JSON Schema for this object.

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[]

Optional list of individual error details

Array items:

ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueunknown

The value at the given location

instancestring

A URI reference that identifies the specific occurrence of the problem.

statusinteger

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring

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

$schemastring

A URL to the JSON Schema for this object.

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[]

Optional list of individual error details

Array items:

ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueunknown

The value at the given location

instancestring

A URI reference that identifies the specific occurrence of the problem.

statusinteger

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring

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

$schemastring

A URL to the JSON Schema for this object.

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[]

Optional list of individual error details

Array items:

ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueunknown

The value at the given location

instancestring

A URI reference that identifies the specific occurrence of the problem.

statusinteger

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring

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

$schemastring

A URL to the JSON Schema for this object.

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[]

Optional list of individual error details

Array items:

ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueunknown

The value at the given location

instancestring

A URI reference that identifies the specific occurrence of the problem.

statusinteger

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring

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

$schemastring

A URL to the JSON Schema for this object.

detailstring

A human-readable explanation specific to this occurrence of the problem.

errorsErrorDetail[]

Optional list of individual error details

Array items:

ErrorDetail

locationstring

Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'

messagestring

Error message text

valueunknown

The value at the given location

instancestring

A URI reference that identifies the specific occurrence of the problem.

statusinteger

HTTP status code

titlestring

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

typestring

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