RecoupGet a Free AuditFree Audit

API REFERENCE

Update Artist

On this page
PATCH/api/artists/{id}

Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.

Authentication

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

Request

cURL
curl --request PATCH \
  --url 'https://api.recoupable.dev/api/artists/YOUR_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "The Weeknd",
  "image": "https://i.scdn.co/image/abc123",
  "instruction": "Always reference the artist'"'"'s R&B catalog when discussing collaborations.",
  "label": "XO / Republic Records",
  "knowledges": [
    {
      "name": "Artist Knowledge Base Report",
      "url": "https://arweave.net/abc123",
      "type": "text/plain"
    }
  ],
  "profileUrls": {
    "SPOTIFY": "https://open.spotify.com/artist/1Xyo4u8uXC1ZmMpatF05PJ",
    "INSTAGRAM": "https://instagram.com/theweeknd",
    "TIKTOK": "https://tiktok.com/@theweeknd",
    "TWITTER": "https://x.com/theweeknd",
    "YOUTUBE": "https://youtube.com/@theweeknd",
    "APPLE": "https://music.apple.com/us/artist/the-weeknd/479756766",
    "FACEBOOK": "https://facebook.com/theweeknd",
    "THREADS": "https://threads.net/@theweeknd",
    "BANDSINTOWN": "https://www.bandsintown.com/a/1371750-the-weeknd"
  },
  "pinned": true
}'

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

Parameters

Path parameters

idstringrequired

Artist account ID to update.

Request body required

Fields to update. At least one field must be provided.

application/json

namestring

Artist display name

imagestring

Artist profile image URL. Pass an empty string to clear the existing image; otherwise must be a valid URL.

instructionstring

Custom AI instruction shown to assistants when this artist is the active context

labelstring

Record label name

knowledgesarray<ArtistKnowledge>

Knowledge base entries for this artist. Replaces the existing array when provided.

Item properties for knowledges
namestringrequired

Display name for the knowledge entry

urlstringrequired

Public URL where the knowledge content is stored

format: uri

typestringrequired

MIME type of the knowledge content

profileUrlsobject

Map of uppercase platform identifier to social profile URL. Each entry replaces the existing social for that platform; platforms not included are preserved. Recognized keys: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS, BANDSINTOWN. Keys are matched case-sensitively, so lowercase keys will create duplicate socials instead of replacing the existing entry.

pinnedboolean

Pin or unpin the artist for the authenticated account. Affects only the caller's pin state, not other accounts.

Responses

200Artist updated successfully

application/json

artistobjectrequired
Properties for artist
account_idstringrequired

UUID of the artist account

format: uuid

namestringrequirednullable

Artist display name

imagestringnullable

Artist profile image URL

instructionstringnullable

Custom AI instruction for this artist

labelstringnullable

Record label name

knowledgesarray<ArtistKnowledge>nullable

Knowledge base entries for this artist

Item properties for knowledges
namestringrequired

Display name for the knowledge entry

urlstringrequired

Public URL where the knowledge content is stored

format: uri

typestringrequired

MIME type of the knowledge content

account_socialsarray<UpdatedArtistSocial>required

Social profiles linked to the artist after the update

Item properties for account_socials
idstring

UUID of the underlying social record

format: uuid

usernamestringnullable

Username on the platform

profile_urlstringnullable

Full profile URL on the platform

linkstring

Profile URL (mirror of profile_url for legacy clients)

typestring

Uppercase platform identifier inferred from the profile URL: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS, or NONE if the URL did not match a known platform.

pinnedbooleanrequired

Whether the authenticated account has pinned this artist

400Bad request - validation error (e.g. invalid image URL, no fields provided)

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

Path to the field that failed validation, when applicable

Item properties for missing_fields

string

errorstringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid authentication

No response body schema is specified.

403Forbidden - the authenticated account cannot update this artist

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

Path to the field that failed validation, when applicable

Item properties for missing_fields

string

errorstringrequired

Error message describing what went wrong

404Artist not found

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

Path to the field that failed validation, when applicable

Item properties for missing_fields

string

errorstringrequired

Error message describing what went wrong

500Internal server error

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

Path to the field that failed validation, when applicable

Item properties for missing_fields

string

errorstringrequired

Error message describing what went wrong

Full specification

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

Download releases.json
View operation source
json
{
  "description": "Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "Artist account ID to update.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "description": "Fields to update. At least one field must be provided.",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateArtistRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Artist updated successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateArtistResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - validation error (e.g. invalid image URL, no fields provided)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateArtistErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid authentication"
    },
    "403": {
      "description": "Forbidden - the authenticated account cannot update this artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateArtistErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateArtistErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateArtistErrorResponse"
          }
        }
      }
    }
  }
}