Developer API

SoundCTRLfor agents

Fandom data for AI assistants such as Meta Muse.

Add to MuseEndpoints

Start here

two urls, no sdk, no sign-up to read the public data

Base URL

https://app.soundctrl.xyz/api/muse/v1

Every path below is relative to it. HTTPS only, JSON only.

OpenAPI document

https://app.soundctrl.xyz/api/muse/v1/openapi.json

Hand this one link to an agent and it can work out the rest. Every endpoint is described in plain words, with the fan question it answers.

Custom connector

Add SoundCTRL to Muse

paste one prompt. muse writes the connector itself and keeps it.

Send this to Muse

Build a custom integration to SoundCTRL. Its OpenAPI document is https://app.soundctrl.xyz/api/muse/v1/openapi.json. Use my SoundCTRL API key for the /me endpoints. I want you to be able to tell me my fan rank, my challenges, my battles, and my rewards.
01

Open Muse and paste the prompt above. Muse reads our OpenAPI document and builds its own client.

02

For the /me answers, create a key in the SOUNDCTRL app under Settings > Muse and give it to Muse when it asks for one.

03

Ask it anything: where you rank, what your challenges are, whether your fandom is losing a battle.

Heads up: we are submitting SOUNDCTRL for an official Meta connector listing. Until it appears in the Muse directory, use the prompt above. It works as soon as the API is live.

Endpoints

every route, the fan question it answers, and what comes back

Shapes that repeat

Responses below are trimmed. These three objects mean the same thing wherever they appear, and a share object is attached to anything a fan would want to post.

Share      { url, image_url, text }        // text = a ready-to-post sentence
ArtistRef  { name, image_url, fandom_url }
TopFan     { username, display_name, points, rank }

PublicNo key

GET/beef?a=<artist>&b=<artist>

Answers

"Who won the Drake vs Kendrick Lamar beef?"

Reads the Stan Wars debate threads where fans have actually voted on the two artists and returns the verdict with the vote split. If nobody has settled it yet you still get a 200, with verdict null and a link to start the debate.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/beef?a=Drake&b=Kendrick%20Lamar"

Response

{
  "question": "Who won the Drake vs Kendrick Lamar beef?",
  "a": {
    "name": "Drake",
    "image_url": "https://cdn.soundctrl.xyz/artists/drake.jpg",
    "fandom_url": "https://app.soundctrl.xyz/fandom/drake"
  },
  "b": {
    "name": "Kendrick Lamar",
    "image_url": "https://cdn.soundctrl.xyz/artists/kendrick.jpg",
    "fandom_url": "https://app.soundctrl.xyz/fandom/kendrick-lamar"
  },
  "verdict": {
    "winner": "b",
    "a_pct": 38,
    "b_pct": 62,
    "votes": 1840,
    "thread_title": "Who actually won it, be honest",
    "top_argument": "Not Like Us ran the entire summer."
  },
  "debate_url": "https://app.soundctrl.xyz/threads/8f2c",
  "share": {
    "url": "https://app.soundctrl.xyz/threads/8f2c",
    "image_url": "https://app.soundctrl.xyz/api/og/muse/beef?a=Drake&b=Kendrick",
    "text": "SoundCTRL fans voted: Kendrick 62%, Drake 38%, 1,840 votes in."
  }
}
GET/artists/{name}/fandom

Answers

"Tell me about the KATSEYE fandom."

The fandom side of an artist, which is the part a general assistant does not know: how many members, who the top fans are, whether a stream battle is running, the lore, and the thread everyone is arguing in right now.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/artists/KATSEYE/fandom"

Response

{
  "artist": {
    "name": "KATSEYE",
    "image_url": "https://cdn.soundctrl.xyz/artists/katseye.jpg",
    "fandom_url": "https://app.soundctrl.xyz/fandom/katseye"
  },
  "fandom": {
    "members": 12480,
    "members_change_7d": 318,
    "ranked_fans": 9042,
    "top_fans": [
      { "username": "eyekandy", "display_name": "Kandy", "points": 48210, "rank": 1 },
      { "username": "gnarlysoph", "display_name": null, "points": 44980, "rank": 2 }
    ],
    "active_battle": {
      "opponent": "TWICE",
      "ends_at": "2026-09-22T23:59:00Z",
      "our_streams": 81422,
      "their_streams": 79980,
      "status": "live"
    },
    "lore": [
      {
        "title": "The Gnarly era, explained",
        "excerpt": "Six members, one debut, and the group chat that named the era.",
        "url": "https://app.soundctrl.xyz/threads/3b1a"
      }
    ],
    "hottest_thread": {
      "title": "Best KATSEYE b-side",
      "type": "poll",
      "comment_count": 214,
      "url": "https://app.soundctrl.xyz/threads/77de"
    }
  },
  "share": { "url": "...", "image_url": "...", "text": "..." }
}

top_fans respects every fan's leaderboard privacy setting, so a fan who hid themselves is not in the list.

GET/fandoms/chart?period=week|all

Answers

"Which fandom is the biggest this week?"

The fandom chart, up to 20 places, with each fandom's member count and how far it moved.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/fandoms/chart?period=week"

Response

{
  "period": "week",
  "entries": [
    {
      "rank": 1,
      "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
      "members": 12480,
      "change": 2
    },
    {
      "rank": 2,
      "artist": { "name": "Olivia Rodrigo", "image_url": "...", "fandom_url": "..." },
      "members": 11907,
      "change": -1
    }
  ],
  "share": { "url": "...", "image_url": "...", "text": "..." }
}
GET/polls?artist=<name>&q=<text>

Answers

"Settle it: best Olivia Rodrigo album?"

Finds up to five live fan polls that match the artist and the words in the question, with current counts and a link to vote.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/polls?artist=Olivia%20Rodrigo&q=best%20album"

Response

{
  "polls": [
    {
      "title": "Best Olivia Rodrigo album?",
      "artist": { "name": "Olivia Rodrigo", "image_url": "...", "fandom_url": "..." },
      "options": [
        { "label": "SOUR", "votes": 1204, "pct": 58 },
        { "label": "GUTS", "votes": 872, "pct": 42 }
      ],
      "total_votes": 2076,
      "vote_url": "https://app.soundctrl.xyz/threads/91cc",
      "share": { "url": "...", "image_url": "...", "text": "..." }
    }
  ]
}
GET/artists/{name}/events?city=<city>

Answers

"When is KATSEYE coming to Los Angeles?"

Tour dates from Bandsintown, filtered by city or region when you pass one.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/artists/KATSEYE/events?city=Los%20Angeles"

Response

{
  "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
  "events": [
    {
      "date": "2026-11-14T20:00:00",
      "venue": "Kia Forum",
      "city": "Inglewood",
      "region": "CA",
      "country": "United States",
      "tickets_url": "https://www.bandsintown.com/e/105344821"
    }
  ],
  "source": "bandsintown"
}

Live third party data with a 4 second timeout and an hour of caching, so an empty events array can mean nothing is announced rather than nothing exists.

GET/threads/hot?artist=<name>&limit=<n>

Answers

"What is the hottest Stan Wars debate about Drake?"

The threads with the most heat right now, for one artist or across the whole app when you leave artist off.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/threads/hot?artist=Drake&limit=3"

Response

{
  "threads": [
    {
      "id": "8f2c",
      "title": "Who actually won it, be honest",
      "type": "debate",
      "artist": "Drake",
      "comment_count": 431,
      "likes": 1290,
      "url": "https://app.soundctrl.xyz/threads/8f2c"
    }
  ]
}
GET/openapi.json

Answers

"What can SoundCTRL do?"

The OpenAPI 3.1 document. This is the only URL an agent needs: every endpoint on this page is described in it, in plain words, so the agent can work out which one answers the question it was asked.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/openapi.json"

Response

{
  "openapi": "3.1.0",
  "info": { "title": "SoundCTRL Fandom API", "version": "1.0.0" },
  "servers": [{ "url": "https://app.soundctrl.xyz/api/muse/v1" }],
  "paths": {
    "/beef": {
      "get": {
        "summary": "Who won the <A> vs <B> beef?",
        "parameters": [{ "name": "a", "in": "query", "required": true }]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer" }
    }
  }
}

AccountKey required

These answer for one fan, so they need that fan's key. Send it as Authorization: Bearer sck_... on every request. Never cached.

GET/me

Answers

"Which fandoms am I in?"

Who the key belongs to, by username, and the fandoms they have joined.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "username": "eyekandy",
  "display_name": "Kandy",
  "fandoms": [
    {
      "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
      "member_since": "2026-03-02T18:41:00Z"
    }
  ]
}
GET/me/rank?artist=<name>

Answers

"Where do I rank among KATSEYE fans?"

The fan's place on one fandom leaderboard, their points, and a share image built for posting. rank is null when the fan has not earned a place yet.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/rank?artist=KATSEYE" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
  "rank": 14,
  "total_fans": 9042,
  "points": 21870,
  "share": {
    "url": "https://app.soundctrl.xyz/fandom/katseye",
    "image_url": "https://app.soundctrl.xyz/api/og/fan-ranking?rank=14",
    "text": "I am #14 of 9,042 KATSEYE fans on SoundCTRL."
  }
}
GET/me/challenges

Answers

"What can I do today to earn points?"

The fan's open challenges and what each one pays. Read only.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/challenges" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "challenges": [
    { "id": "daily_checkin", "title": "Check in today", "points": 25, "completed": true },
    { "id": "stream_three", "title": "Stream 3 songs", "points": 50, "completed": false }
  ]
}
GET/me/battles

Answers

"Is my fandom in a stream battle right now?"

Every battle the fan's fandoms are in, with both stream counts and when it ends, which is what an agent needs to nudge somebody to play the album before the clock runs out.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/battles" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "battles": [
    {
      "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
      "opponent": "TWICE",
      "ends_at": "2026-09-22T23:59:00Z",
      "our_streams": 81422,
      "their_streams": 79980,
      "status": "live"
    }
  ]
}
GET/me/rewards?artist=<name>

Answers

"Do I have enough points for the signed vinyl?"

The fan's points balance and what the artist is offering, with claimable telling you whether they can afford it yet. Read only, so claiming still happens in the app.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/rewards?artist=KATSEYE" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "points_balance": 21870,
  "rewards": [
    {
      "id": "signed-vinyl",
      "title": "Signed vinyl",
      "cost_points": 25000,
      "claimable": false,
      "url": "https://app.soundctrl.xyz/rewards/signed-vinyl"
    }
  ]
}
GET/me/faves/activity

Answers

"What have my friends been up to on SoundCTRL?"

What the fans you follow have joined and how their ranks moved in the last week, by username only.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/faves/activity" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "faves": [
    {
      "username": "gnarlysoph",
      "display_name": null,
      "joined_fandoms_7d": ["TWICE"],
      "rank_changes": [{ "artist": "KATSEYE", "from": 6, "to": 2 }]
    }
  ]
}

No listening history, ever. What your friends played is not in this response and is not available anywhere in this API.

GET/me/summary

Answers

"How am I doing on SoundCTRL this week?"

One call for the whole picture: every rank, the next battle, the points balance, and a share object. Built for an agent that checks in on a schedule and reports back without being asked.

Request

curl "https://app.soundctrl.xyz/api/muse/v1/me/summary" \
  -H "Authorization: Bearer sck_YOUR_KEY"

Response

{
  "fandoms": [
    {
      "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
      "rank": 14,
      "total_fans": 9042,
      "points": 21870
    },
    {
      "artist": { "name": "Olivia Rodrigo", "image_url": "...", "fandom_url": "..." },
      "rank": 302,
      "total_fans": 8811,
      "points": 4120
    }
  ],
  "next_battle": {
    "artist": { "name": "KATSEYE", "image_url": "...", "fandom_url": "..." },
    "opponent": "TWICE",
    "ends_at": "2026-09-22T23:59:00Z"
  },
  "points_balance": 21870,
  "share": { "url": "...", "image_url": "...", "text": "..." }
}

Authentication

public data needs nothing. personal data needs the fan's own key.

01

Public endpoints

No auth, no key, no account. Charts, fandom profiles, polls, debates, threads and tour dates are open, because they are already public in the app.

02

Keys for /me

A fan creates their own key in the SOUNDCTRL app under Settings > Muse. It starts with sck_ and it is theirs, not yours: there is no developer account here, and no key that reads somebody else's data.

curl "https://app.soundctrl.xyz/api/muse/v1/me/summary" \
  -H "Authorization: Bearer sck_YOUR_KEY"
  • A key is shown once, when it is created. We store only a hash of it, so we cannot show it again and nobody at SOUNDCTRL can read it back. Lost it? Revoke it and make another.
  • Revoke anytime. Tap revoke in Settings > Muse and the key stops working on the next request. Up to five active keys per account, so you can give one assistant a key without disturbing another.
  • A bad or revoked key gets 401 INVALID_KEY. Treat it as a prompt to ask the fan for a fresh key rather than as an outage.
  • Keys belong in your assistant's credential flow, never in a chat message. Muse handles API keys that way by design. Anything holding an sck_ key can read that fan's rank, points, battles and rewards, so treat it like a password.
Read before you build

Limits and rules

  • Usernames only, no personal data, ever. Fans appear as a username and a display name, and only where the app already shows them publicly. No emails, no wallet addresses, no user ids, no tokens, no payout data, no location, and no listening history. There is no endpoint that returns any of it.
  • Fans who hid themselves stay hidden. Anyone who turned off leaderboard visibility in the app is left out of every list this API returns.
  • SOUNDCTRL is 13+, and your integration has to be too. Fans must be 13 or older to have an account. A large share of them are teenagers, so do not build anything that profiles them, contacts them, or moves their data somewhere we cannot see it.
  • Public reads are cached for 60 seconds. A successful public response carries Cache-Control: public, s-maxage=60 with a five minute stale-while-revalidate window. Errors are never cached. Polling faster than once a minute buys you nothing.
  • Rate limits. 120 requests a minute per key on the /me endpoints. Public endpoints are limited by IP at the edge, and the routes that call a third party, such as tour dates, are limited more tightly than the rest. Over the line you get a 429, so back off and retry.
  • Read only in v1. Nothing here writes. No posting to Stan Wars, no voting, no claiming rewards, no spending points. Points are earned in the app, never through this API.
  • Fields get added, never renamed. Parse defensively, ignore what you do not recognise, and expect new fields without warning.
Good to know

Commonly asked questions

By name, case-insensitive, or by the SoundCTRL artist id. Never by a streaming service id. If we do not know the artist you get a 404 ARTIST_NOT_FOUND with a suggestions list of the closest names we do know, so an agent can ask the fan which one they meant.

Always JSON, always the same two fields: { "error": "CODE", "message": "a human sentence" }, with a 4xx or 5xx status. The code is for your logic, the message is safe to read out to the fan.

A bad or revoked key gets 401 INVALID_KEY, so mint a fresh one in Settings > Muse. Until linking is fully switched on, /me endpoints answer 401 INVALID_KEY and the app's Settings > Muse screen will say so. Public endpoints keep working either way.

Bandsintown, called live with a 4 second timeout and cached for an hour. Everything else on this page comes from SoundCTRL itself.

Not in v1. Every endpoint on this page is read only. Nothing here posts to Stan Wars, votes in a poll, claims a reward, or spends points. Points are earned in the app, never through this API.

No. We see the API calls your assistant makes and nothing else. Your assistant holds your key; we never hold your assistant.

Support

Building something on this, stuck on an endpoint, or need a shape we do not return yet? Email us and a human answers.

info@soundctrl.xyz

Using the API means following our Terms and Conditions and Privacy Policy.

Logo

Where Fandom Is Currency

Get Rewards for Streaming. Yapping. And Building Lore

Docs

How it worksFAQ'sFor ArtistsDownload AppFor CreatorsDevelopersPress

Legal

Terms and ConditionsPrivacy Policy

Follow Us

InstagramTiktokYoutubeX (Twitter)