> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Unified music research search. This is the discovery primitive for the detail-lookup endpoints — use `type=artists` to find an `id` for [GET /api/research/albums](/api-reference/research/albums), `type=tracks` for [GET /api/research/track](/api-reference/research/track), `type=playlists` for [GET /api/research/playlist](/api-reference/research/playlist), etc. Pick the right `id` from the returned results and pass it to the appropriate detail endpoint.

Searches the configured research data source. Use the `type` and `limit` parameters to narrow results before passing a returned `id` to a detail endpoint.



## OpenAPI

````yaml api-reference/openapi/research.json GET /api/research
openapi: 3.1.0
info:
  title: Recoup API - Research
  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
security: []
paths:
  /api/research:
    get:
      description: >-
        Unified music research search. This is the discovery primitive for the
        detail-lookup endpoints — use `type=artists` to find an `id` for [GET
        /api/research/albums](/api-reference/research/albums), `type=tracks` for
        [GET /api/research/track](/api-reference/research/track),
        `type=playlists` for [GET
        /api/research/playlist](/api-reference/research/playlist), etc. Pick the
        right `id` from the returned results and pass it to the appropriate
        detail endpoint.


        Searches the configured research data source. Use the `type` and `limit`
        parameters to narrow results before passing a returned `id` to a detail
        endpoint.
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Search query. Can be a name (e.g. `Drake`, `Flowers`) or a
            streaming-platform URL (e.g. `https://open.spotify.com/artist/...`).
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: 'Entity type to search: artists, tracks, or labels.'
          schema:
            type: string
            enum:
              - artists
              - tracks
              - labels
            default: artists
        - name: limit
          in: query
          required: false
          description: Maximum number of results.
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          required: false
          description: Pagination offset. Defaults to 0 when omitted.
          schema:
            type: string
            pattern: ^(0|[1-9][0-9]*)$
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchSearchResponse'
        '400':
          description: Validation error (e.g., missing required query parameter `q`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchErrorResponse'
        '401':
          description: Authentication failed — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchErrorResponse'
        '501':
          $ref: '#/components/responses/ResearchDataSourceUnsupported'
components:
  schemas:
    ResearchSearchResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
            - error
          example: success
        results:
          type: array
          description: Matching artists with IDs, names, and basic metadata.
          items:
            $ref: '#/components/schemas/ResearchSearchResult'
    ResearchErrorResponse:
      type: object
      required:
        - status
        - error
      description: >-
        Error response returned by all research endpoints for validation
        failures (400) and authentication errors (401).
      properties:
        status:
          type: string
          enum:
            - error
          example: error
        error:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Missing required parameter: artist'
    ResearchSearchResult:
      type: object
      description: >-
        Search result. Additional type-specific identifier fields pass through.
        The set depends on `type` (artists | tracks | labels).
      properties:
        id:
          type: string
          description: Provider-neutral ID.
        name:
          type: string
        avatar:
          type: string
          nullable: true
        site_url:
          type: string
          nullable: true
      additionalProperties: true
  responses:
    ResearchDataSourceUnsupported:
      description: >-
        The configured research data source does not support this endpoint or
        data shape.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResearchErrorResponse'
          example:
            status: error
            error: Request failed with status 501

````