# Create Artist

Source: https://recoupable.dev/docs/api-reference/artists/create

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.

## POST /api/artists

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/artists": {
      "post": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateArtistRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "The name of the artist to create"
          },
          "spotify_artist_id": {
            "type": "string",
            "description": "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_id": {
            "type": "string",
            "format": "uuid",
            "description": "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."
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional organization ID to link the new artist to"
          }
        }
      },
      "CreateArtistResponse": {
        "type": "object",
        "required": [
          "artist"
        ],
        "properties": {
          "artist": {
            "$ref": "#/components/schemas/CreatedArtist"
          }
        }
      },
      "CreateArtistError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "missing_fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of missing or invalid field names"
          },
          "error": {
            "type": "string",
            "description": "Error message describing the validation failure"
          },
          "message": {
            "type": "string",
            "description": "Error message (for invalid JSON or other errors)"
          }
        }
      },
      "Error": {
        "required": [
          "error",
          "message"
        ],
        "type": "object",
        "properties": {
          "error": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "CreatedArtist": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the created artist account"
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist account (same as id)"
          },
          "name": {
            "type": "string",
            "description": "Name of the artist"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "ISO timestamp of when the artist was created"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "ISO timestamp of when the artist was last updated"
          },
          "image": {
            "type": "string",
            "nullable": true,
            "description": "Artist profile image URL"
          },
          "instruction": {
            "type": "string",
            "nullable": true,
            "description": "Custom AI instruction for this artist"
          },
          "knowledges": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "description": "Knowledge base references for this artist"
          },
          "label": {
            "type": "string",
            "nullable": true,
            "description": "Record label name"
          },
          "organization": {
            "type": "string",
            "nullable": true,
            "description": "Organization name"
          },
          "company_name": {
            "type": "string",
            "nullable": true,
            "description": "Company name"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "description": "Job title"
          },
          "role_type": {
            "type": "string",
            "nullable": true,
            "description": "Role type"
          },
          "onboarding_status": {
            "type": "string",
            "nullable": true,
            "description": "Onboarding status"
          },
          "onboarding_data": {
            "nullable": true,
            "description": "Onboarding data"
          },
          "account_info": {
            "type": "array",
            "description": "Account info records"
          },
          "account_socials": {
            "type": "array",
            "description": "Linked social media accounts"
          }
        }
      }
    }
  }
}
```