# Set or clear an artist link

Source: https://docs.musicnerd.net/api-reference/artist-links/direct-edit-link

Set or clear an artist link

## POST /api/directEditLink

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

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

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

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: artist links",
    "version": "1.0.0",
    "description": "Writing, ordering, checking and reviewing the platform links on an artist's profile."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/directEditLink": {
      "post": {
        "summary": "Set or clear an artist link",
        "operationId": "postDirectEditLink",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Writes one platform link straight onto the artist, for the approved claimant or an admin, and returns the platform written. `set` reads the platform and ID from `url`: song and album URLs are refused, and an Apple Music or Beatport artist page is saved as an approved Lore source instead (`siteName` is then `applemusic` or `beatport`). `clear` empties the platform's link. For Spotify or Deezer, disconnect requires `expectedValue`, the account ID actually displayed to the user (explicit null means an empty slot). The server rechecks the current identity, claim generation and authorization, archives the complete matching mapping provenance privately, removes that active mapping, clears the direct link and cancels pending identity-match jobs atomically. A stale or divergent mapping is refused for review. No exclusion is added, and a later explicit valid replacement still uses normal collision checks. The private archive is not returned.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "artistId",
                  "action"
                ],
                "properties": {
                  "artistId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "set",
                      "clear"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "description": "The profile URL to save. Required for `set`."
                  },
                  "siteName": {
                    "type": "string",
                    "description": "The platform column to empty. Required for `clear`."
                  },
                  "expectedValue": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 1,
                    "description": "Required for Spotify/Deezer clear. Send the displayed account ID, not a freshly inferred replacement. Explicit null means already disconnected; omission is invalid. Other platforms do not require it."
                  }
                }
              },
              "examples": {
                "set": {
                  "value": {
                    "artistId": "6cb3d81a-3d02-4c57-a711-bb7902a9af1b",
                    "action": "set",
                    "url": "https://www.instagram.com/p3t3rango/"
                  }
                },
                "clear": {
                  "value": {
                    "artistId": "6cb3d81a-3d02-4c57-a711-bb7902a9af1b",
                    "action": "clear",
                    "siteName": "instagram"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Written. `siteName` and `platformName` come back for `set`; `platformName` is the urlmap display name and may be null.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "success"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "success": {
                      "type": "boolean"
                    },
                    "siteName": {
                      "type": "string",
                      "description": "The column written, or `applemusic` / `beatport` for a source-backed link."
                    },
                    "platformName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "changed": {
                      "type": "boolean",
                      "description": "For ordinary profile-link set only: whether the stored ID changed. Omitted for clear and source-backed additions."
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "success": true,
                  "siteName": "instagram",
                  "platformName": "Instagram"
                }
              }
            }
          },
          "400": {
            "description": "Missing or wrong input: `artistId and action are required`, `artistId must be a UUID`, `action must be 'set' or 'clear'`, `url is required for set action`, `siteName is required for clear action`, `Add an artist profile link, not a song or album.`, or the platform is not supported (`We don't support that link yet — we currently accept links from a fixed set of platforms. Check the \"Supported links\" list to see them.`). Catalog disconnect without a valid `expectedValue` is refused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "url is required for set action"
                }
              }
            }
          },
          "401": {
            "description": "No valid access token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not signed in"
                }
              }
            }
          },
          "403": {
            "description": "The user is not the artist's approved claimant or an admin (`Not authorized for this artist`), or the claim changed while writing (`Artist ownership changed; this operation was cancelled.`). Catalog writes recheck the current approved claim generation and live role; a changed claim or revoked role is refused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not authorized for this artist"
                }
              }
            }
          },
          "409": {
            "description": "The id belongs to another artist (`That spotify artist ID is already linked to a different artist`, `That spotify artist ID conflicts with an existing artist mapping`; same for `deezer`), or the Apple Music / Beatport page is already in Lore (`This link has already been suggested. Review it in Lore.`) or another account is already connected on that platform (`A different account is already connected. Remove the existing link before approving this replacement.`). `code` is always `CONFLICT`. Catalog clear also refuses a changed displayed identity or full mapping, including a retained mapping that differs from the direct account. Refresh and review before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConflictError"
                }
              }
            }
          },
          "500": {
            "description": "The write failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Internal server error"
                }
              }
            }
          },
          "503": {
            "description": "Catalog disconnect could not be confirmed because its storage capability or transaction was unavailable. Refresh before retrying; a transport failure during commit can have an uncertain outcome. There is no field-only fallback.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ConflictError": {
        "type": "object",
        "required": [
          "status",
          "error",
          "code"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "CONFLICT"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access token",
        "description": "The signed-in user's access token. Copy it at https://musicnerd.net/access after signing in. Link writes need the artist's approved claimant or a Music Nerd admin; `removeArtistData` accepts any whitelisted user too."
      }
    }
  }
}
```
