# Search

Source: https://recoupable.dev/docs/api-reference/spotify/search

Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.

## GET /api/spotify/search

Full OpenAPI specification: https://recoupable.dev/docs/spec/social.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Social",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/spotify/search": {
      "get": {
        "description": "Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "The search query keywords and optional field filters",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "A comma-separated list of item types to search across: album, artist, playlist, track, show, episode, audiobook",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "market",
            "in": "query",
            "description": "An ISO 3166-1 alpha-2 country code or 'from_token'",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (default: 20, min: 1, max: 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "The index of the first result to return (default: 0, max: 10000)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpotifySearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpotifyErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SpotifySearchResponse": {
        "type": "object",
        "properties": {
          "artists": {
            "$ref": "#/components/schemas/SpotifyArtistsPaginated",
            "description": "Search results for artists (if type includes artist)"
          },
          "albums": {
            "type": "object",
            "description": "Search results for albums (if type includes album)"
          },
          "tracks": {
            "type": "object",
            "description": "Search results for tracks (if type includes track)"
          },
          "playlists": {
            "type": "object",
            "description": "Search results for playlists (if type includes playlist)"
          }
        }
      },
      "SpotifyErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code"
              },
              "message": {
                "type": "string",
                "description": "Error message"
              }
            },
            "description": "Error details"
          }
        }
      },
      "SpotifyArtistsPaginated": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "A link to the Web API endpoint returning the full result"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifyArtistObject"
            },
            "description": "List of artist objects"
          },
          "limit": {
            "type": "integer",
            "description": "The maximum number of items in the response"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL to the next page of items"
          },
          "offset": {
            "type": "integer",
            "description": "The offset of the items returned"
          },
          "previous": {
            "type": "string",
            "nullable": true,
            "description": "URL to the previous page of items"
          },
          "total": {
            "type": "integer",
            "description": "The total number of items available"
          }
        }
      },
      "SpotifyArtistObject": {
        "type": "object",
        "properties": {
          "external_urls": {
            "$ref": "#/components/schemas/SpotifyExternalUrls"
          },
          "followers": {
            "$ref": "#/components/schemas/SpotifyFollowers"
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A list of the genres the artist is associated with"
          },
          "href": {
            "type": "string",
            "description": "A link to the Web API endpoint providing full details"
          },
          "id": {
            "type": "string",
            "description": "The Spotify ID for the artist"
          },
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifyImage"
            },
            "description": "Images of the artist in various sizes"
          },
          "name": {
            "type": "string",
            "description": "The name of the artist"
          },
          "popularity": {
            "type": "integer",
            "description": "The popularity of the artist (0-100)"
          },
          "type": {
            "type": "string",
            "enum": [
              "artist"
            ],
            "description": "The object type, always 'artist'"
          },
          "uri": {
            "type": "string",
            "description": "The Spotify URI for the artist"
          }
        }
      },
      "SpotifyExternalUrls": {
        "type": "object",
        "properties": {
          "spotify": {
            "type": "string",
            "description": "The Spotify URL for the object"
          }
        }
      },
      "SpotifyFollowers": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "nullable": true,
            "description": "This will always be set to null"
          },
          "total": {
            "type": "integer",
            "description": "The total number of followers"
          }
        }
      },
      "SpotifyImage": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The source URL of the image"
          },
          "height": {
            "type": "integer",
            "nullable": true,
            "description": "The image height in pixels"
          },
          "width": {
            "type": "integer",
            "nullable": true,
            "description": "The image width in pixels"
          }
        }
      }
    }
  }
}
```