# List link suggestions

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

List link suggestions

## GET /api/artist/{id}/link-suggestions

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/artist/{id}/link-suggestions": {
      "get": {
        "summary": "List link suggestions",
        "operationId": "getArtistLinkSuggestions",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "The links contributors and research have proposed for the artist, pending first then newest, 100 per page, for the approved claimant or an admin. Song and album URLs are left out. Who suggested or reviewed each one is a display name only: `Automated research` for research, `Not recorded` when hidden or unknown.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The artist's id (a UUID).",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "6cb3d81a-3d02-4c57-a711-bb7902a9af1b"
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Where the page starts; 0 to 100000.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "items",
                    "hasMore",
                    "nextOffset"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LinkSuggestion"
                      }
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "nextOffset": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "The `offset` for the next page, or null on the last one."
                    }
                  }
                },
                "example": {
                  "status": "ok",
                  "items": [
                    {
                      "id": "0f3a7c62-1d7e-4b1e-9a7a-5b1f0c0e2a11",
                      "kind": "ugc",
                      "url": "https://www.instagram.com/p3t3rango/",
                      "title": "instagram",
                      "platform": "instagram",
                      "hidden": false,
                      "status": "pending",
                      "origin": "submission",
                      "submittedAt": "2026-10-20T18:02:11.000Z",
                      "suggestedBy": {
                        "id": "4d1a2b3c-0000-4000-8000-000000000042",
                        "name": "musicnerd_fan"
                      },
                      "reviewedAt": null,
                      "reviewedBy": null
                    }
                  ],
                  "hasMore": false,
                  "nextOffset": null
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "`private, no-store`: the list is the caller's, never shared or cached.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID (`Invalid artist ID`) or `offset` is not an integer in range (`Invalid page offset`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Invalid page offset"
                }
              }
            }
          },
          "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.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not authorized for this artist"
                }
              }
            }
          },
          "500": {
            "description": "The list could not be loaded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Could not load link suggestions"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LinkSuggestion": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "url",
          "title",
          "platform",
          "hidden",
          "status",
          "origin",
          "submittedAt",
          "suggestedBy",
          "reviewedAt",
          "reviewedBy"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "ugc",
              "source"
            ],
            "description": "A contributor's UGC submission, or a Lore source."
          },
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "The platform name for UGC; the source's title, else the destination's label, else `Website`."
          },
          "platform": {
            "type": "string",
            "description": "The platform column for UGC; the destination's platform for a source, else `website`."
          },
          "hidden": {
            "type": "boolean",
            "description": "True when an approved source's icon was removed from the profile."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "origin": {
            "type": "string",
            "description": "`submission`, `research`, `upload` or `unknown`."
          },
          "submittedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "suggestedBy": {
            "$ref": "#/components/schemas/Person"
          },
          "reviewedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "reviewedBy": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Person"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Person": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "description": "A display name only; no email or wallet. `id` is null and `name` is `Not recorded` when the account is hidden or unknown; research shows as `Automated research`.",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "name": {
            "type": "string"
          }
        }
      }
    },
    "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."
      }
    }
  }
}
```
