soundcloud.md

cloud's unofficial SoundCloud API documentation

THIS DOCUMENT WAS LAST UPDATED ON 01-07-2022.

This document goes over both the private parts of the API as well as some undocumented quirks of the public facing one. Read the SoundCloud API docs and visit the OpenAPI explorer for full public endpoint documentation.

Please try the endpoints for yourself in your favourite request client for more information.

Prerequisites:

• Language
  • In this document, SoundCloud will be abbreviated to SC.
  • All the schemas used in this document are defined in the OpenAPI explorer.
• URL
  • Base URL is https://api-v2.soundcloud.com unless stated otherwise.
• Authorization
  • Auth is either done with the Authorization: OAuth <authkey> request header or the ?client_id=<clientid> URL param.
  • Client id is static, meaning that it does not change, and is the more stable form of authorization. (unconfirmed)
• Versioning
  • The side effects of ?app_version= URL param are unknown. The API responds fine without it present, but It may be some sort of subversioning on SC's side. It is recomended to keep it set to 1656488185, because that's the version when this document was written.
• Localization
  • While the ?app_locale= URL param does not seem to do anything for API endpoints (not proven), and it's not known wether it defaults to English or users' locale. It is recomended to keep it set to en to avoid any unexpected behaviour.
• Response format
  • As of the time of writing of this document, all endpoints return JSON. In their guide, SC always sets the accept header to accept: application/json; charset=utf-8.

---

GET /mixed-selections

Returns the front page playlists like "Recently Played" or "More of what you like" as a list of collections.
WARNING: The response is somewhat big (750KiB).

Return schema: Playlists

URL params:

param	value	comment
variant_ids		optional, is left empty when called by from official client.
limit	10	optional, default 50 probably
offset	0	optional, default 0
linked_partitioning	1	enables linked partitioning

---

GET /me/suggested/users/who_to_follow

Returns a collection of algorithmic follow recomendation (the one in the top right of the frontpage).

URL params:

param	value	comment
view	recommended-first
limit	21	optional, default 50 probably
offset	0	optional, default 0
linked_partitioning	1	enables linked partitioning

---

GET /me/connected-applications

Returns a collection of connected applications and their descriptions.

Return schema: ConnectedApps

URL params:

param	value	comment
limit	10	optional, default 50 probably
offset	0	optional, default 0
linked_partitioning	1	enables linked partitioning

---

GET /me/settings/privacy

Returns user's privacy settings.

Return schema: Privacy

URL params:

param	value	comment

---

PUT /me/settings/privacy

Changes user's privacy settings and returns them.
The request json should contain any of fields from GET /me/settings/privacy.

Return schema: Privacy

URL params:

param	value	comment

---

PUT /me

Changes user's information and returns newly set values.
The request json should contain any of the fields from the Me schema.

URL params:

param	value	comment

---

Undefined schemas

Privacy

{
    "allows_messages_from_unfollowed_users": <bool>,
    "analytics_id": <string>,
    "analytics_opt_in": <bool>,
    "communications_opt_in": <bool>,
    "legislation": <array>,
    "targeted_advertising_opt_in": <bool>
}

ConnectedApp

{
      "id": <string>,
      "urn": <string>,
      "owner": <string>,
      "name": <string>,
      "description": <string>,
      "url": <string>
}

ConnectedApps

{
    "collection": [<ConnectedAPP>],
    "next_href": <string>
}