API REFERENCE

Create Artist

On this page

POST/api/artists

Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.

Authentication

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

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/artists' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string"
}'

Request body required

Artist creation parameters

application/json

namestringrequired

The name of the artist to create

minLength: 1

spotify_artist_idstring

Optional Spotify artist id. When provided, the endpoint resolves-or-creates the canonical artist for that id: if an artist already carries it, that artist is linked to the account and returned (200) instead of creating a duplicate; otherwise the artist is created with its Spotify profile attached (201).

account_idstring

UUID of the account to create the artist for. Only applicable when the authenticated account has access to multiple accounts via organization membership. If not provided, the artist is created for the API key's own account.

format: uuid

organization_idstring

Optional organization ID to link the new artist to

format: uuid

Responses

200Existing canonical artist for the given spotify_artist_id linked to the account (no new artist created)

application/json

artistobjectrequired

Properties

idstring

UUID of the created artist account

format: uuid

account_idstring

UUID of the artist account (same as id)

format: uuid

namestring

Name of the artist

created_atstringnullable

ISO timestamp of when the artist was created

format: date-time

updated_atstringnullable

ISO timestamp of when the artist was last updated

format: date-time

imagestringnullable

Artist profile image URL

instructionstringnullable

Custom AI instruction for this artist

knowledgesarray<string>nullable

Knowledge base references for this artist

Item properties

string

labelstringnullable

Record label name

organizationstringnullable

Organization name

company_namestringnullable

Company name

job_titlestringnullable

Job title

role_typestringnullable

Role type

onboarding_statusstringnullable

Onboarding status

onboarding_dataanynullable

Onboarding data

account_infoarray<any>

Account info records

account_socialsarray<any>

Linked social media accounts

201Artist created successfully

application/json

artistobjectrequired

Properties

idstring

UUID of the created artist account

format: uuid

account_idstring

UUID of the artist account (same as id)

format: uuid

namestring

Name of the artist

created_atstringnullable

ISO timestamp of when the artist was created

format: date-time

updated_atstringnullable

ISO timestamp of when the artist was last updated

format: date-time

imagestringnullable

Artist profile image URL

instructionstringnullable

Custom AI instruction for this artist

knowledgesarray<string>nullable

Knowledge base references for this artist

Item properties

string

labelstringnullable

Record label name

organizationstringnullable

Organization name

company_namestringnullable

Company name

job_titlestringnullable

Job title

role_typestringnullable

Role type

onboarding_statusstringnullable

Onboarding status

onboarding_dataanynullable

Onboarding data

account_infoarray<any>

Account info records

account_socialsarray<any>

Linked social media accounts

400Bad request - validation error or invalid JSON

application/json

statusstring · enum

Status of the request

Values: "error"

missing_fieldsarray<string>

List of missing or invalid field names

Item properties

string

errorstring

Error message describing the validation failure

messagestring

Error message (for invalid JSON or other errors)

500Internal server error

application/json

errorintegerrequired

format: int32

messagestringrequired

Full specification

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

Download releases.json

View operation source

json

{
  "description": "Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.",
  "requestBody": {
    "description": "Artist creation parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateArtistRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Existing canonical artist for the given spotify_artist_id linked to the account (no new artist created)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateArtistResponse"
          }
        }
      }
    },
    "201": {
      "description": "Artist created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateArtistResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - validation error or invalid JSON",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateArtistError"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}