API & Integrations

Bring listening activity, music discoveries, collections and artist earnings into your dashboard.

Connect your account

1. Sign in to your Wavyl account and open key management. Regular accounts can manage their own key.
2. Generate a personal read-only key and copy it when shown. If a key is already active, use your saved copy or coordinate replacement before revoking it.
3. Connect the key to your trusted dashboard. Send it in the Authorization: Bearer YOUR_KEY header from your server.

Keep keys encrypted on the server. Do not place them in URLs, public pages, browser code, source control or shared documents. Revoke a key on the source site to stop future API reads; data already cached by a dashboard may remain until its private cache expires.

Available calls

Append a route below to this base URL:

Expand a call to see its parameters, request and response. Examples use fictional data and may omit fields; they are not your account data or a live quote.

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "id": 42,
  "username": "example_user",
  "display_name": "Example User",
  "scope": "dashboard:read",
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/listening-stats' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "summary": {
    "recorded_play_events": 120,
    "distinct_played_items": 30,
    "liked_items": 8,
    "following_artists": 5,
    "followers": 12
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/recently-played?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "track",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8,
      "last_played_at": "2026-11-05T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/likes?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "track",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8,
      "liked_at": "2026-11-05T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/playlists?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "playlist",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/releases?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "track",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/following-releases?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "track",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/me/earnings?page=1&per_page=6' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_KEY'

{
  "items": [
    {
      "id": 123,
      "music": {
        "id": 123,
        "title": "Example track",
        "url": "https://www.wavyl.com/listen/example-track/",
        "artwork": null,
        "kind": "track",
        "artist": "Example Artist",
        "genres": [
          "Electronic"
        ],
        "recorded_plays": 120,
        "likes": 8
      },
      "amount_mlx": "1000",
      "status": "paid",
      "updated_at": "2026-11-05T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "by_status": {
    "paid": {
      "count": 1,
      "amount_mlx": "1000"
    }
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/charts?page=1&per_page=6' \
  --header 'Accept: application/json'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "track",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8,
      "rank": 1,
      "period_plays": 20
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "period_key": "post-count-week-202632",
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/charts/weekly?page=1&per_page=6' \
  --header 'Accept: application/json'

{
  "items": [],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 0,
    "total_pages": 0
  },
  "chart_week": null,
  "updated_at": "2026-11-05T12:00:00Z"
}

curl --request GET \
  --url 'https://www.wavyl.com/wp-json/wavyl/v1/dashboard/featured-playlists?page=1&per_page=6' \
  --header 'Accept: application/json'

{
  "items": [
    {
      "id": 123,
      "title": "Example track",
      "url": "https://www.wavyl.com/listen/example-track/",
      "artwork": null,
      "kind": "playlist",
      "artist": "Example Artist",
      "genres": [
        "Electronic"
      ],
      "recorded_plays": 120,
      "likes": 8
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 6,
    "total": 1,
    "total_pages": 1
  },
  "updated_at": "2026-11-05T12:00:00Z"
}

Parameters and limits

page: integer 1–10000; per_page: integer 1–50. Lists default to 6 items. Personal keys have a soft limit of 120 requests per minute. Source view models may be cached for 60 seconds.

Amounts such as MLX and USD cents may be decimal strings. Preserve their precision instead of converting large values to floating-point numbers. Use the returned pagination totals. Times shown in examples are ISO 8601 UTC; display dates in the user’s timezone.

What the data means

Play events are not listening minutes or unique listeners. Only published, password-free music is returned; no playable audio URLs are exposed. Artist earnings are not a wallet balance. Unclaimed earnings are not guaranteed withdrawable. Charts identify the stored period and may be older than the current week.

Response handling

Use the HTTP status for error handling. Error bodies vary by route. Keep cached personal data private and short-lived; handle missing values and empty lists.

Optional PHP client

The API works with any language that can make HTTPS requests. A WordPress PHP reference client and README are also available as a convenience.