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 '{
  "pinned": true
}'

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

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

idpath · stringrequired

Request bodyapplication/json

cURL for this request

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/artists/{id}' \
  --header 'Content-Type: application/json' \
  --data '{
  "pinned": true
}'

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

Example: "The Weeknd"

imagestring

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

Example: "https://i.scdn.co/image/abc123"

instructionstring

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

Example: "Always reference the artist's R&B catalog when discussing collaborations."

labelstring

Record label name

Example: "XO / Republic Records"

knowledgesarray<ArtistKnowledge>

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

Item properties

namestringrequired

Display name for the knowledge entry

Example: "Artist Knowledge Base Report"

urlstringrequired

Public URL where the knowledge content is stored. New entries use Supabase Storage; existing legacy URLs remain readable. Anyone with the URL can read the content without authentication.

Example: "https://exampleproject.supabase.co/storage/v1/object/public/public-uploads/example/knowledge.txt"

format: uri

typestringrequired

MIME type of the knowledge content

Example: "text/plain"

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.

Example: {"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"}

pinnedboolean

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

Pin for the authenticated account

{
  "pinned": true
}

Unpin for the authenticated account

unpin

{
  "pinned": false
}

Responses

200Artist updated successfully

application/json

artistobjectrequired

Properties

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

namestringrequired

Display name for the knowledge entry

Example: "Artist Knowledge Base Report"

urlstringrequired

Public URL where the knowledge content is stored. New entries use Supabase Storage; existing legacy URLs remain readable. Anyone with the URL can read the content without authentication.

Example: "https://exampleproject.supabase.co/storage/v1/object/public/public-uploads/example/knowledge.txt"

format: uri

typestringrequired

MIME type of the knowledge content

Example: "text/plain"

account_socialsarray<UpdatedArtistSocial>required

Social profiles linked to the artist after the update

Item properties

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, for example INSTAGRAM or LINKEDIN. Unrecognized or empty URLs produce NONE.

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

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

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

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

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

{
  "operationId": "patchArtistsById",
  "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"
        },
        "examples": {
          "pin": {
            "summary": "Pin for the authenticated account",
            "value": {
              "pinned": true
            }
          },
          "unpin": {
            "summary": "Unpin for the authenticated account",
            "value": {
              "pinned": false
            }
          }
        }
      }
    }
  },
  "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"
          }
        }
      }
    }
  }
}

Get started with Recoup.

Try Our Platform

Build Your Platform

Update artist

Authentication

Request

Try it

Parameters

Path parameters

Request body required

Responses

Full specification