# Search artists

Source: https://docs.musicnerd.net/api-reference/lookups/search-artists

Search artists

## POST /api/searchArtists

Full OpenAPI specification: https://docs.musicnerd.net/spec/artist-lookups.json

## Authentication

This operation's specification permits a request without authentication.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: artist lookups",
    "version": "1.0.0",
    "description": "Public lookups: an artist by Spotify ID or Instagram handle, an artist's X handle, artist search, track links, the contributor leaderboard and an artist's image. No credentials. Each endpoint answers in its own shape, with plain-text errors, not this API's `{ status }` envelope."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/searchArtists": {
      "post": {
        "summary": "Search artists",
        "description": "Searches Music Nerd and Deezer by name, or resolves a Spotify/Deezer artist ID or artist URL. Exact saved provider ownership is returned first without a direct provider lookup. Saved explicit URLs/URIs need no provider requests. Bare IDs also run the normal ranked name search so numeric artist names remain searchable, including when direct lookup is unavailable. Conflicting saved ownership returns 409 instead of presenting either profile as authoritative. Otherwise a direct lookup returns an external result for the existing add/review flow, without creating or linking an artist.",
        "operationId": "searchArtists",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Artist name, 22-character Spotify ID, positive numeric Deezer ID, spotify:artist:<id>, or an HTTPS artist URL on open.spotify.com or deezer.com (including locale paths and share parameters). Track/album URLs and unsupported URLs return 400; short redirect links are not followed."
                  },
                  "bookmarkedArtistIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "description": "Artists the caller has bookmarked; they rank first within a match tier."
                  }
                }
              },
              "example": {
                "query": "Example Artist",
                "bookmarkedArtistIds": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked name results or exact provider identity results. Local artists carry public identity/link columns with bio null; external artists have id null. A missing provider artist returns no direct result. Bare inputs retain usable local/external name matches even when direct lookup is unavailable, and are not cached so a later request can recover the direct identity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "results"
                  ],
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "$ref": "#/components/schemas/SearchArtistResult"
                          },
                          {
                            "$ref": "#/components/schemas/ExternalArtistResult"
                          }
                        ]
                      }
                    }
                  }
                },
                "example": {
                  "results": [
                    {
                      "id": "6cb3d81a-0000-4000-8000-000000000000",
                      "name": "Example Artist",
                      "spotify": "4Z8W4fKeB5YxbusRsdQVPb",
                      "deezer": "11600",
                      "bandcamp": null,
                      "youtube": null,
                      "youtubechannel": null,
                      "instagram": "exampleartist",
                      "x": "exampleartist",
                      "facebook": null,
                      "tiktok": null,
                      "customImage": null,
                      "match_type": 0,
                      "bio": null,
                      "isExternalOnly": false,
                      "imageUrl": "https://e-cdns-images.dzcdn.net/images/artist/0000000000000000deadbeef/250x250-000000-80-0-0.jpg",
                      "matchScore": 0,
                      "linkCount": 2
                    },
                    {
                      "id": null,
                      "name": "Example Artist II",
                      "platformId": "11601",
                      "platform": "deezer",
                      "imageUrl": "https://e-cdns-images.dzcdn.net/images/artist/0000000000000000deadbeef/1000x1000-000000-80-0-0.jpg",
                      "profileUrl": "https://www.deezer.com/artist/11601",
                      "isExternalOnly": true,
                      "matchScore": 1,
                      "linkCount": 0
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or unsupported/non-artist URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                },
                "example": {
                  "error": "Invalid query parameter"
                }
              }
            }
          },
          "408": {
            "description": "The search did not finish within 12 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                },
                "example": {
                  "error": "Search timed out. Please try a more specific search term."
                }
              }
            }
          },
          "409": {
            "description": "The supplied provider identity has contradictory saved ownership, including different direct-column and mapping owners. No provider fallback, artist creation, or identity attachment occurs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "This artist ID has conflicting saved profiles. Please try searching by name."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "The body is not JSON, or the database could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                },
                "example": {
                  "error": "Internal server error"
                }
              }
            }
          },
          "503": {
            "description": "Direct provider lookup unavailable, including shared Spotify cooldown. Explicit URLs/URIs return 503; bare IDs return usable name matches when available, otherwise 503. Failures are not cached as empty results."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchArtistResult": {
        "type": "object",
        "description": "A Music Nerd artist in search results.",
        "required": [
          "id",
          "name",
          "spotify",
          "deezer",
          "bandcamp",
          "youtube",
          "youtubechannel",
          "instagram",
          "x",
          "facebook",
          "tiktok",
          "customImage",
          "match_type",
          "bio",
          "isExternalOnly",
          "imageUrl",
          "matchScore",
          "linkCount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "spotify": {
            "type": [
              "string",
              "null"
            ]
          },
          "deezer": {
            "type": [
              "string",
              "null"
            ]
          },
          "bandcamp": {
            "type": [
              "string",
              "null"
            ]
          },
          "youtube": {
            "type": [
              "string",
              "null"
            ]
          },
          "youtubechannel": {
            "type": [
              "string",
              "null"
            ]
          },
          "instagram": {
            "type": [
              "string",
              "null"
            ]
          },
          "x": {
            "type": [
              "string",
              "null"
            ]
          },
          "facebook": {
            "type": [
              "string",
              "null"
            ]
          },
          "tiktok": {
            "type": [
              "string",
              "null"
            ]
          },
          "customImage": {
            "type": [
              "string",
              "null"
            ]
          },
          "match_type": {
            "type": "integer",
            "description": "0 for a substring match on the name, 1 for a similarity match."
          },
          "bio": {
            "type": "null",
            "description": "Always `null`; the About comes from the claim-checked lookups."
          },
          "isExternalOnly": {
            "type": "boolean",
            "const": false
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "The artist's upload, else their Spotify or Deezer picture."
          },
          "matchScore": {
            "type": "integer",
            "description": "0 exact, 1 prefix, 2 substring, 3 similarity only."
          },
          "linkCount": {
            "type": "integer",
            "description": "How many of the returned link columns are set."
          }
        }
      },
      "ExternalArtistResult": {
        "type": "object",
        "description": "A Spotify or Deezer artist not yet in Music Nerd.",
        "required": [
          "id",
          "name",
          "platformId",
          "platform",
          "imageUrl",
          "profileUrl",
          "isExternalOnly",
          "matchScore",
          "linkCount"
        ],
        "properties": {
          "id": {
            "type": "null"
          },
          "name": {
            "type": "string"
          },
          "platformId": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "spotify",
              "deezer"
            ]
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "profileUrl": {
            "type": "string"
          },
          "isExternalOnly": {
            "type": "boolean",
            "const": true
          },
          "matchScore": {
            "type": "integer"
          },
          "linkCount": {
            "type": "integer",
            "const": 0
          }
        }
      },
      "ErrorMessage": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```
