API REFERENCE

Get Artist Profile

On this page

GET/api/artists/{id}/profile

Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.

No authentication. This endpoint is deliberately public and unbilled — it backs the shareable artist page at chat.recoupable.dev/artists/{id} and can be called without an API key. Only public fields are returned; account settings, instructions, and valuation data are never included.

Responses are cacheable (Cache-Control: public, s-maxage=300, stale-while-revalidate=600), so a value may be up to a few minutes stale.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/artists/YOUR_ID/profile' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the artist account.

Responses

200Artist profile retrieved successfully.

application/json

idstringrequired

The artist's account id.

format: uuid

namestringrequired

The artist's display name.

imagestringrequirednullable

URL of the artist's profile image, or null when none is set.

socialsarray<ArtistPublicProfileSocial>required

Connected social profiles, empty when none are linked.

Item properties

typestringrequired

Platform name derived from the profile URL, e.g. SPOTIFY, INSTAGRAM, TIKTOK, YOUTUBE.

usernamestringrequirednullable

The artist's handle on the platform, when known.

profile_urlstringrequired

Public URL of the profile on the platform.

catalogsarray<ArtistPublicProfileCatalog>required

Catalogs linked to the artist, newest first; empty when none are linked.

Item properties

idstringrequired

The catalog id.

format: uuid

namestringrequired

The catalog's display name.

song_countintegerrequired

Number of songs currently in the catalog.

updated_atstringrequired

When the catalog last changed.

format: date-time

songsarray<ArtistPublicProfileSong>required

The catalog's songs crediting this artist, sorted by plays descending and capped at the top 50 — song_count reflects the full catalog and may exceed songs.length.

Item properties

isrcstringrequired

The song's ISRC.

namestringrequired

The song's title.

albumstringrequirednullable

The album or release the song belongs to, when known.

artwork_urlstringrequirednullable

Apple Music artwork URL for the song's release, or null when artwork has not been resolved yet.

playsintegerrequired

The song's latest captured Spotify play count. Captures are periodic, so this can lag the live number.

est_value_usdnumberrequired

Estimated value of the song in USD — the mid point of the published Recoup valuation model applied to this song's plays.

valuationobjectrequirednullable

Estimated value band for the artist's catalog(s), from the published Recoup valuation model over all credited songs' latest play counts. Null when the artist has no measured songs.

Properties

lownumberrequired

Low end of the estimated catalog value band, USD.

midnumberrequired

Mid estimate of the catalog value, USD.

highnumberrequired

High end of the estimated catalog value band, USD.

404No artist with this id. Returned for unknown ids and for accounts that are not artists — the two cases are deliberately indistinguishable, so the endpoint cannot be used to probe which account ids exist.

application/json

statusstring · enumrequired

Always error.

Values: "error"

errorstringrequired

Human-readable error message.

404 example

{
  "status": "error",
  "error": "Artist not found"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json

View operation source

json

{
  "description": "Public artist profile: the artist's name, image, connected social profiles, and linked catalogs in one call.\n\n**No authentication.** This endpoint is deliberately public and unbilled — it backs the shareable artist page at `chat.recoupable.dev/artists/{id}` and can be called without an API key. Only public fields are returned; account settings, instructions, and valuation data are never included.\n\nResponses are cacheable (`Cache-Control: public, s-maxage=300, stale-while-revalidate=600`), so a value may be up to a few minutes stale.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier (UUID) of the artist account.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artist profile retrieved successfully.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPublicProfileResponse"
          }
        }
      }
    },
    "404": {
      "description": "No artist with this id. Returned for unknown ids and for accounts that are not artists — the two cases are deliberately indistinguishable, so the endpoint cannot be used to probe which account ids exist.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPublicProfileErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Artist not found"
          }
        }
      }
    }
  }
}