# David Place API

Base URL: https://next.david.place

## Authentication

API endpoints require a bearer token.

Send it with each API request:

Authorization: Bearer $DAVID_PLACE_API_SECRET

Never print, log, commit, or otherwise expose the secret.

## Endpoints

### POST /api/album-search

Searches the album catalog by album name and/or artist.

Request body:

```json
{ "name": "Album title", "artist": "Artist name", "limit": 5 }
```

At least one of `name` or `artist` is required. Returns MusicBrainz release-group
and release IDs together with Spotify and TIDAL metadata for MusicBrainz-curated links.

### POST /api/spotify-search

Searches Spotify for an album.

Request body:

```json
{ "artist": "Artist name", "album": "Album title", "spotifyId": "optional exact album ID" }
```

Returns matching albums with identifying metadata. Every returned album is saved
so its `spotifyId` can be used with `POST /api/suggestion-sets`. When supplied,
`spotifyId` is fetched directly if ordinary search does not return it.

### POST /api/suggestion-sets

Creates an album suggestion set from albums previously returned
by `POST /api/spotify-search`.

Request body:

```json
{
  "type": "ad-hoc",
  "prompt": "The request these suggestions answer",
  "idempotencyKey": "a stable key for safe retries",
  "suggestions": [
    { "spotifyId": "...", "explanation": "Why this album is suggested" }
  ]
}
```

`type` must be either `ad-hoc` or `weekly-recs`. The order of
`suggestions` is preserved. Requests may contain 1–20 unique albums.
Retrying with the same `idempotencyKey` returns the existing set.

Successful response:

```json
{
  "suggestionSetId": "...",
  "url": "https://next.david.place/suggestions/..."
}
```

The `url` is the public page where the completed suggestions can be viewed.