Artists

Artist management for album and track associations with smart duplicate prevention

Resource Overview

Artists represent individual performers, bands, or musical entities. The system implements intelligent find-or-create logic to prevent duplicate artists for the same user.

Base Endpoint
/artists
Resource Type
artists
User Scope
Owner-restricted

Smart Artist Creation

The API automatically prevents duplicate artists. If an artist with the same name already exists for the owner — the artist's owner_user_id, normally the authenticated user — the system returns the existing artist instead of creating a duplicate, ensuring data consistency.

To create a genuine homonym (two different people sharing a stage name), send meta: { "allow-duplicate-name": true } on the POST document. This always inserts a new artist, even when the name is already taken by that owner; a non-boolean value is rejected with 422. On PATCH the flag creates nothing, but a non-boolean value is still rejected with 422.

Schema

Required Attributes

Field Type Validation Description
name string Required · up to 255 characters Artist name

Optional Attributes

Field Type Validation Description
bio string Optional Artist biography or description

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last update timestamp

Relationships

Relationship Related Resource Description Editable
album-artists album-artists Album associations with artist roles
dsp-availabilities artist-dsp-availabilities Artist identifications on DSPs (Spotify, Apple Music, etc.)

Related Endpoints

Endpoint Method Description Documentation
/artists/{id}/trends GET Get performance trends for an artist (plays by date, DSP, country) View Trends →

List Artists

GET /artists 
GET /artists
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[name] - Filter by artist name
  • • filter[bio] - Search in biography
  • • filter[created-at] - Filter by creation date

Other Parameters

  • • include - Include related resources
  • • sort - Sort by field
  • • page[number] - Page number
  • • page[size] - Results per page

Success Response

200 OK 
{
  "data": [
    {
      "type": "artists",
      "id": "1",
      "attributes": {
        "name": "John Smith",
        "bio": "Singer-songwriter from Nashville",
        "created-at": "2024-01-01T10:00:00Z",
        "updated-at": "2024-01-01T10:00:00Z"
      },
      "relationships": {
        "album-artists": {
          "data": [
            { "type": "album-artists", "id": "1" },
            { "type": "album-artists", "id": "2" }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 25,
      "last-page": 2
    }
  }
}

Create Artist

POST /artists 
{
  "data": {
    "type": "artists",
    "attributes": {
      "name": "New Artist",
      "bio": "Emerging artist with unique sound"
    }
  }
}

Smart Creation Logic

Find-or-Create Behavior

If artist exists: Returns existing artist, optionally updates bio if provided

If artist doesn't exist: Creates new artist with provided data

Matching criteria: Same name + same owner user

Creating a Homonym on Purpose

Opt out of the find-or-create match for this one request by adding meta.allow-duplicate-name:

{
  "data": {
    "type": "artists",
    "attributes": {
      "name": "John Smith"
    },
    "meta": {
      "allow-duplicate-name": true
    }
  }
}

This always inserts a new artist row, even though an artist named "John Smith" already exists for this owner. Once created, attach its DSP identifiers like any other artist, via POST /artist-dsp-availabilities against the new artist's id.

Success Response

201 Created 
{
  "data": {
    "type": "artists",
    "id": "42",
    "attributes": {
      "name": "New Artist",
      "bio": "Emerging artist with unique sound",
      "created-at": "2024-08-19T10:00:00Z",
      "updated-at": "2024-08-19T10:00:00Z"
    }
  }
}

Existing Artist Response

If an artist with the same name already exists for the same owner, the response is still 201 Created, carrying the existing artist and its original id:

201 Created 
{
  "data": {
    "type": "artists",
    "id": "15",
    "attributes": {
      "name": "Existing Artist",
      "bio": "Updated bio if provided",
      "created-at": "2024-01-01T10:00:00Z",
      "updated-at": "2024-08-19T10:00:00Z"
    }
  }
}

Update Artist

PATCH /artists/{id} 
{
  "data": {
    "type": "artists",
    "id": "1",
    "attributes": {
      "name": "Updated Artist Name",
      "bio": "Updated biography with more details"
    }
  }
}

Success Response

200 OK 
{
  "data": {
    "type": "artists",
    "id": "1",
    "attributes": {
      "name": "Updated Artist Name",
      "bio": "Updated biography with more details",
      "updated-at": "2024-08-19T10:15:00Z"
    }
  }
}

Delete Artist

DELETE /artists/{id} 
DELETE /artists/1
Authorization: Bearer {token}

Dependency Check

Artists with existing album associations cannot be deleted. Remove all album-artist relationships first.

Success Response

204 No Content

Usage Examples

Bulk Artist Creation

Create multiple artists without worrying about duplicates:

const artists = ['John Smith', 'Jane Doe', 'John Smith'];

for (const name of artists) {
  await fetch('/artists', {
    method: 'POST',
    body: JSON.stringify({
      data: { type: 'artists', attributes: { name } }
    })
  });
}
// John Smith will only be created once — unless a request explicitly
// sends meta: { 'allow-duplicate-name': true }, which is how two
// different people who both go by "John Smith" get separate records.

Search Artists

Find artists by name or bio content:

Search by name
GET /artists?filter[name]=john
Search in bio
GET /artists?filter[bio]=singer
Include album associations
GET /artists?include=album-artists
Include DSP availabilities
GET /artists?include=dsp-availabilities,dsp-availabilities.dsp

Best Practices

Data Quality

  • • Use consistent naming conventions
  • • Provide meaningful biographies
  • • Avoid special characters in names
  • • Check for existing artists before creation
  • • Update bios when adding new artists

Performance

  • • Use the smart creation feature to prevent duplicates — reserve meta.allow-duplicate-name for genuine homonyms, since every use of it is a row a repeat POST can no longer collapse back down
  • • Include relationships when needed
  • • Filter by name for better search performance
  • • Paginate large artist lists
  • • Cache frequently accessed artist data