Melodreams Developer API

Introduction #

The Melodreams Developer API reads public profiles and your own account data over HTTPS. The base URL is https://api-dev1.melodreams.com.

https://api-dev1.melodreams.com

Every endpoint is a GET and returns JSON. Every request except /health and /v1/scopes needs a bearer token from an account on an active paid plan. The API is server-side only and rejects browser origins by CORS, so hold the token on a server you control. Create a token in the developer portal.

Authentication #

Send a bearer token in the Authorization header on every request. This is the only transport. There is no query-parameter or cookie auth.

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     --header "Accept: application/json" \
     "https://api-dev1.melodreams.com/v1/me"

A request with no header returns 401 missing_token and a WWW-Authenticate: Bearer challenge. ?token= and ?api_key= do nothing: a credential in a URL leaks into access logs, shell history, and Referer headers.

Token format #

A token is one opaque string of 75 characters, built from four parts. The parts are shown so you can recognise a token and tell two of your own apart. Your code should never take it apart. The example below is not a working credential.

Get a token #

1. Sign in to a Melodreams account on an active paid plan.
2. Open the developer portal. The session cookie is shared, so there is no second sign-in.
3. Go to token management and create a token: give it a name (1 to 60 characters), pick its scopes, and pick an expiry.
4. Copy the token immediately. The full string is shown once and is never recoverable. If you lose it, revoke it and create another.

Token management is session-authenticated only. An API token cannot create, list, or revoke tokens, including itself. Scopes and expiry are fixed at creation: to change them, mint a new token and revoke the old one. You can hold up to 5 active tokens per account.

Expiry options are 1, 7, 30, 90, or 365 days, or never. Prefer the shortest expiry your deployment can absorb, so rotation is enforced rather than remembered. An expired token returns 401 token_expired.

Making requests #

The cheapest call to confirm a token works is GET /v1/me. It needs a valid token but no scope, and reports the account, scopes, and limits the token carries. Here it is with curl and with the SDK.

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     "https://api-dev1.melodreams.com/v1/me"

import { Melodreams } from '@heymelodreams/sdk';

const mdr = new Melodreams(process.env.MELODREAMS_API_TOKEN);

const me = await mdr.me();
console.log(`Token for @${me.username}, tier ${me.tier}`);

Set the token in your environment first and read it from there. Never hardcode it.

export MELODREAMS_API_TOKEN="mdr_live_..."

The same first call with Python and requests:

import os
import requests

BASE = "https://api-dev1.melodreams.com"
token = os.environ["MELODREAMS_API_TOKEN"]

response = requests.get(
    BASE + "/v1/me",
    headers={"Authorization": "Bearer " + token, "Accept": "application/json"},
    timeout=10,
)
response.raise_for_status()
me = response.json()["data"]
print("Token for @{}, tier {}".format(me["username"], me["tier"]))

Response format #

Every /v1 response uses one of two shapes. Success carries data. An error carries a code you switch on. You never branch on which endpoint produced an error.

{
  "ok": true,
  "data": { }
}

{
  "ok": false,
  "error": "insufficient_scope",
  "message": "This endpoint requires the \"analytics:read\" scope. This token has: public:read.",
  "docs": "https://api-dev1.melodreams.com/docs#insufficient_scope"
}

ok

boolean true on success, false on error.

data

object The endpoint payload. Present on success only.

error

string A stable snake_case code. Present on error only. Switch on this.

message

string Human-readable text for logs. May be reworded at any time, and is often more specific than the generic text in the error reference. Never parse it.

docs

string A link to the matching row in the error reference.

• HTTPS only. Plain HTTP is upgraded, never served.
• Responses are application/json; charset=utf-8 with X-Content-Type-Options: nosniff.
• Timestamps are ISO 8601 in UTC, for example 2026-07-22T09:58:12.004Z. That includes X-RateLimit-Reset, which is not a Unix epoch.
• Unknown fields are dropped, not passed through. The profile shapes are a projection of internal storage, so an editor change in the dashboard is not a breaking API change.
• A known path called with a method other than GET returns 404 not_found, not 405.

Rate limits #

Two request limits apply per token, enforced independently. The burst limit is 120 requests per 60 seconds; exceeding it returns 429 rate_limited and clears within a minute, so retry with backoff. The monthly quota is 50,000 requests per token; exhausting it returns 429 quota_exceeded, which does not clear by retrying.

Limits are keyed on the token id, not on your IP address, so it does not matter how many hosts your integration runs on. The monthly quota resets at 00:00 UTC on the 1st of each calendar month, not on your billing anniversary. The reset instant is returned in X-RateLimit-Reset.

Distinct profiles #

public:read carries a third limit: a token may read at most 500 distinct profiles per UTC day. The 501st new username returns 429 distinct_profile_cap. The word that matters is distinct. Re-reading a username you already fetched today does not count again, so a widget refreshing the same 20 profiles all day touches 20 of your 500. Only breadth is capped, never depth. This limit does not clear by retrying or by trying a different username; it resets at 00:00 UTC.

Headers #

Successful responses, and the two metered 429s (quota_exceeded and distinct_profile_cap), carry your remaining monthly budget, so you can watch consumption without spending a request.

• These headers are attached to 2xx responses and to 429 quota_exceeded and 429 distinct_profile_cap. They are not present on 401, 402, 403, 404, or burst 429 rate_limited, which are rejected before metering runs. Read them defensively.
• The quota is per token, not per account, so a development token cannot spend production's 50,000.

Errors #

Errors use the error envelope. The error field is the contract: a fixed vocabulary of stable snake_case codes. Branch on it and log it. The code and the HTTP status never disagree.

{
  "ok": false,
  "error": "plan_required",
  "message": "This endpoint requires an active Melodreams subscription.",
  "docs": "https://api-dev1.melodreams.com/docs#plan_required"
}

Retry policy #

• Retry rate_limited, any 5xx (internal_error, upstream_error, api_unavailable, scope_paused), and network errors, with exponential backoff and jitter and a cap on attempts. For api_unavailable and scope_paused, wait for the Retry-After window.
• Do not retry quota_exceeded. It clears on the 1st of the month. Alert instead.
• Do not retry distinct_profile_cap, and do not route around it with a different username. It clears at 00:00 UTC. If you hit it, the shape of the integration is what to change. See Distinct profiles.
• Never retry any other 4xx. A 401, 402, or 403 needs a human: a new token, a subscription, or a different scope.

Error codes #

Scopes #

Scopes are chosen when a token is created and are fixed for its lifetime. A token that lacks a required scope gets 403 insufficient_scope, and the message names the scope required and the scopes the token has. Scopes are additive and least privilege: grant the narrowest set that works, and mint a new token to widen access.

Every scope in v1 is a read. There is no write scope and no webhook scope, because no code path in the API mutates or exports anything. Scope strings never change meaning: a widened capability ships as a new string, so a token issued under the old meaning cannot silently gain access.

The live catalogue is served by GET /v1/scopes. The paid-feature column marks scopes gated by plan in the product: analytics is not available to free accounts anywhere. That is separate from the plan requirement, which applies to the whole API regardless of scope.

Endpoints #

Six endpoints. All GET. All read-only.

GET /health #

curl --silent "https://api-dev1.melodreams.com/health"

{
  "ok": true,
  "service": "developer-api",
  "version": "v1",
  "ready": true,
  "mode": "ok",
  "cache": { "entries": 412, "max": 5000 },
  "timestamp": "2026-07-22T10:31:04.118Z"
}

GET /v1/scopes #

curl --silent "https://api-dev1.melodreams.com/v1/scopes"

{
  "ok": true,
  "data": {
    "scopes": [
      {
        "scope": "public:read",
        "description": "Read any public Melodreams profile.",
        "requires_subscription": false
      },
      {
        "scope": "profile:read",
        "description": "Read the token owner's own profile, links and theme.",
        "requires_subscription": false
      },
      {
        "scope": "analytics:read",
        "description": "Read the token owner's profile view and link click counters.",
        "requires_subscription": true
      }
    ]
  }
}

GET /v1/me #

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     "https://api-dev1.melodreams.com/v1/me"

{
  "ok": true,
  "data": {
    "user_id": "8f2b1c44-7d6e-4a19-b3c0-5e91d2a7f004",
    "username": "aurora",
    "org_id": null,
    "account_type": "user",
    "tier": "full",
    "subscribed": true,
    "token": {
      "id": "Zk9xQ2pM7vTb1sYwLd4NrA",
      "environment": "live",
      "scopes": ["analytics:read", "profile:read", "public:read"]
    },
    "limits": {
      "requests_per_minute": 120,
      "requests_per_month": 50000
    }
  }
}

GET /v1/profiles/:username #

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     "https://api-dev1.melodreams.com/v1/profiles/aurora"

{
  "ok": true,
  "data": {
    "username": "aurora",
    "display_name": "Aurora",
    "bio": "Producer. Night shift. Mixing in Berlin.",
    "avatar_url": "https://img.melodreams.com/u/aurora/avatar.webp",
    "banner_url": null,
    "theme": "midnight",
    "avatar": {
      "shape": "circle",
      "border": true,
      "border_color": "#3b82f6",
      "frame": "none",
      "frame_color": null
    },
    "links": [
      {
        "title": "Latest release",
        "url": "https://open.spotify.com/album/4kaurora",
        "style": "big",
        "type": "music"
      },
      {
        "title": "Tour dates",
        "url": "https://aurora.example/tour",
        "style": "small",
        "type": "standard"
      }
    ],
    "badges": {
      "verified": true,
      "staff": false,
      "developer": false
    },
    "flags": {
      "access_code_required": false,
      "status_dot": true,
      "discoverable": true,
      "listable": true
    },
    "custom_domain": null,
    "melo_bio_mode": "both",
    "updated_at": "2026-07-19T21:04:33.512Z"
  }
}

GET /v1/me/profile #

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     "https://api-dev1.melodreams.com/v1/me/profile"

{
  "ok": true,
  "data": {
    "username": "aurora",
    "display_name": "Aurora",
    "bio": "Producer. Night shift. Mixing in Berlin.",
    "avatar_url": "https://img.melodreams.com/u/aurora/avatar.webp",
    "banner_url": null,
    "theme": "midnight",
    "avatar": {
      "shape": "circle",
      "border": true,
      "border_color": "#3b82f6",
      "frame": "none",
      "frame_color": null
    },
    "links": [
      {
        "title": "Latest release",
        "url": "https://open.spotify.com/album/4kaurora",
        "style": "big",
        "type": "music"
      }
    ],
    "badges": {
      "verified": true,
      "staff": false,
      "developer": false
    },
    "flags": {
      "access_code_required": false,
      "status_dot": true,
      "discoverable": true,
      "listable": true
    },
    "custom_domain": null,
    "melo_bio_mode": "both",
    "updated_at": "2026-07-19T21:04:33.512Z",
    "visibility": {
      "is_public": true,
      "custom_domain_redirect": false,
      "reserved_style": "hidden"
    }
  }
}

GET /v1/me/analytics #

curl --silent \
     --header "Authorization: Bearer ${MELODREAMS_API_TOKEN}" \
     "https://api-dev1.melodreams.com/v1/me/analytics"

{
  "ok": true,
  "data": {
    "views": 18422,
    "clicks": {
      "total": 4310,
      "by_link": [
        {
          "link_id": "lnk_9f2a",
          "title": "Latest release",
          "url": "https://open.spotify.com/album/4kaurora",
          "style": "big",
          "count": 2871
        },
        {
          "link_id": "lnk_3c1b",
          "title": "Tour dates",
          "url": "https://aurora.example/tour",
          "style": "small",
          "count": 1102
        }
      ]
    },
    "updated_at": "2026-07-22T09:58:12.004Z"
  }
}

Versioning #

The version is in the path. Everything under /v1 keeps its shape. A breaking change ships as a new path, /v2; /v1 is not altered in place.

These changes are additive and can ship without notice, so parse defensively and ignore fields you do not recognise:

• New endpoints, new response fields, and new optional query parameters.
• New scopes. An existing token does not gain them; mint a new token to get them.

These are breaking and ship as /v2:

• Removing or renaming a field, narrowing a type, or changing the meaning of an existing value.
• Adding a required parameter or tightening a limit.

Error codes are frozen. A shipped error value never changes meaning; only its message is reworded. Tokens are opaque, so never parse a token to infer a version or anything else.

SDKs and OpenAPI #

The official SDK is TypeScript, has zero dependencies, and is server-side only.

npm i @heymelodreams/sdk

Construct a client with one token. Each method mirrors one endpoint and returns the data payload. Any non-ok response throws a typed MelodreamsError with code and status, so you apply the retry policy by branching on err.code.

import { Melodreams, MelodreamsError } from '@heymelodreams/sdk';

const mdr = new Melodreams(process.env.MELODREAMS_API_TOKEN);

try {
  const me = await mdr.me();
  console.log(`Token for @${me.username}, tier ${me.tier}`);

  const profile = await mdr.profile('aurora');
  console.log(`${profile.display_name}: ${profile.links.length} links`);

  const stats = await mdr.myAnalytics();
  console.log(`${stats.views} views, ${stats.clicks.total} clicks`);
} catch (err) {
  if (err instanceof MelodreamsError) {
    console.error(`${err.code} (${err.status})`);
    process.exit(1);
  }
  throw err;
}

OpenAPI spec #

The full API is described by an OpenAPI 3.1 document, served from this documentation site. It covers every path, parameter, response schema, error code, and rate-limit header on this page.

/docs/openapi.json

Save the file, then point any generator at it for a typed client. The first command below emits TypeScript types with no runtime dependency; the second generates a full client in most mainstream languages.

npx openapi-typescript ./openapi.json --output melodreams.d.ts

npx @openapitools/openapi-generator-cli generate \
  --input-spec ./openapi.json \
  --generator-name python \
  --output ./melodreams-client