Songlist API

Version: 2.0.0

Export

Download

Copy URL

post/songs/bulk-delete-filtered

Delete every song matching the given filters

Deletes every song matching the supplied filters. With no filters set this deletes the streamer's entire songlist. Deletes of more than 500 songs are logged without snapshots and cannot be reverted, so this is the streamer's call alone — tokens belonging to a channel admin are refused.

Authorization

Required scopes

streamer.song.writeWrite streamer songs

Request Bodyrequired

application/json

Schema

DeleteAllSongsParamsBody

$schemastring

A URL to the JSON Schema for this object.

activestring

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

truefalse

attributesinteger[]

Only delete songs carrying every one of these attributes

Array items:

integer (int32)

collabstring

Only delete songs every accepted collab guest also has

only

durationMaxinteger

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

durationMininteger

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

favoritesstring

Only delete the authenticated user's favorited songs

only

inQueuestring

Only delete songs with this queue status

allexcludeonly

isNewboolean

Only delete songs that are new

lastPlayedAfterstring

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

lastPlayedBeforestring

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

searchstring

Only delete songs matching this title/artist search

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",
  "streamerId": 1,
  "timesPlayedOp": "eq",
  "timesPlayedValue": 0
}

Responses

200OK

application/json

Schema

DeleteAllSongsResponseBody

$schemastring

A URL to the JSON Schema for this object.

deletedCountintegerrequired

Example

{
  "$schema": "https://example.com",
  "deletedCount": 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"
}