# Photo choices

Source: https://docs.musicnerd.net/api-reference/artist-images/photo-choice

Photo choices

## GET /api/artist/photo-choice

Full OpenAPI specification: https://docs.musicnerd.net/spec/artist-images.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 images",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/artist/photo-choice": {
      "get": {
        "summary": "Photo choices",
        "operationId": "getPhotoChoices",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "The provider photos an artist can pick as their profile photo: one option each for Deezer and Spotify, from the IDs linked on the artist. `expectedCustomImage` is the current photo; pass it to [Choose a provider photo](/api-reference/artist-images/choose-photo) so a stale choice is refused.",
        "parameters": [
          {
            "name": "artistId",
            "in": "query",
            "required": true,
            "description": "The artist's ID (a UUID).",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "aab92f80-f9e1-4299-aa33-7dd85c8de5d3"
          }
        ],
        "responses": {
          "200": {
            "description": "The two provider options. `Cache-Control: no-store`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhotoChoices"
                },
                "example": {
                  "status": "ok",
                  "expectedCustomImage": null,
                  "options": [
                    {
                      "source": "deezer",
                      "providerId": "5590",
                      "imageUrl": "https://e-cdns-images.dzcdn.net/images/artist/0a1b2c3d4e5f/1000x1000-000000-80-0-0.jpg"
                    },
                    {
                      "source": "spotify",
                      "providerId": null,
                      "imageUrl": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`artistId` is missing or isn't a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Invalid artist"
                }
              }
            }
          },
          "401": {
            "description": "No token, an invalid or expired token, or no Music Nerd user for it. `Cache-Control: no-store`, like every answer on this path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not signed in"
                }
              }
            }
          },
          "403": {
            "description": "The user is neither the artist's claimant nor an admin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Not authorized for this artist"
                }
              }
            }
          },
          "404": {
            "description": "No artist with that ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Artist not found"
                }
              }
            }
          },
          "503": {
            "description": "The database could not be read (including while checking the token).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "status": "error",
                  "error": "Could not load photo choices"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PhotoChoices": {
        "type": "object",
        "required": [
          "status",
          "expectedCustomImage",
          "options"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "expectedCustomImage": {
            "type": [
              "string",
              "null"
            ],
            "description": "The artist's current `customImage`. Send it back as `expectedCustomImage` when choosing."
          },
          "options": {
            "type": "array",
            "description": "One entry per provider, Deezer first, whether or not the artist has that provider linked.",
            "items": {
              "type": "object",
              "required": [
                "source",
                "providerId",
                "imageUrl"
              ],
              "properties": {
                "source": {
                  "$ref": "#/components/schemas/PhotoSource"
                },
                "providerId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The provider ID linked on the artist, trimmed; `null` when none is linked."
                },
                "imageUrl": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The provider's photo for that ID (`https` only); `null` when there is no ID, no photo, or the provider could not be reached."
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "PhotoSource": {
        "type": "string",
        "enum": [
          "deezer",
          "spotify"
        ],
        "description": "Which provider the photo comes from."
      }
    },
    "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. The user must be the artist's approved claimant or a Music Nerd admin."
      }
    }
  }
}
```
