Search API Documentation

Documentation for the Search REST API endpoint. The search endpoint provides natural language and structured searching capabilities across tracks in a library.

Endpoints

GET /api/v1/libraries/{library_id}/searches

Retrieve a list of searches for a specific library.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Query Parameters

Name Type Description
page integer Page number for pagination (default: 1)

Response

{
    "pagination": {
        "total_entries": 25,
        "per_page": 5,
        "current_page": 1,
        "total_pages": 5,
        "next_page": 2,
        "next_page_url": "http://127.0.0.1:3000/api/v1/libraries/2/searches?page=2"
    },
    "searches": [
        {
            "id": 1,
            "library_id": 2,
            "original_search_id": null,
            "remote_identifier": "search_123",
            "search_params": {
                "nls": "Find me some upbeat rock songs",
                "filter": {
                    "and": [
                        {"genre": {"value": "Rock"}},
                        {"active": {"value": true}}
                    ]
                },
                "sort": [["total_score", "desc"], ["title", "asc"]]
            },
            "total_rows": 15,
            "overflow": false,
            "archived": false,
            "error_message": null,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:36:56.251-05:00",
            "searches_tracks": [
                {
                    "track_id": 123,
                    "score": 95.5
                }
            ],
            "url": "http://127.0.0.1:3000/api/v1/libraries/2/searches/1"
        }
    ]
}

Response Fields

Field Type Description
id integer Unique identifier for the search
library_id integer ID of the library
original_search_id integer ID of the parent search for continued conversations
remote_identifier string Client-provided identifier
search_params object Search parameters including NLS, filters, and sort
total_rows integer Number of tracks found
overflow boolean Whether more results exist than returned
archived boolean Whether the search has been archived
error_message string Error message if search failed
searches_tracks array List of matching tracks with scores
url string URL to the search details

POST /api/v1/libraries/{library_id}/searches

Create a new search.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Request Body

Field Type Description Required
remote_identifier string Client-provided identifier No
ai_prompt_name string Name of AI prompt to use No
original_search_id integer ID of parent search for continued conversations No
search_params object Search parameters (see below) Yes

The search_params object can contain:

  • nls: Natural language search string
  • filter: Structured filter object
  • sort: Array of [field, direction] pairs

Example request body:

{
    "remote_identifier": "client_search_123",
    "ai_prompt_name": "music_search",
    "search_params": {
        "nls": "Find me some upbeat rock songs",
        "filter": {
            "and": [
                {
                    "genre": {
                        "value": "Rock"
                    }
                },
                {
                    "active": {
                        "value": true
                    }
                },
                {
                    "not": {
                        "or": [
                            {
                                "mood": {
                                    "value": "Happy"
                                }
                            },
                            {
                                "cover_song": {
                                    "value": false
                                }
                            }
                        ]
                    }
                }
            ]
        },
        "sort": [
            ["total_score", "desc"],
            ["title", "asc"]
        ]
    }
}

Filter Structure

The filter object supports boolean operations and nested conditions:

  • and: Array of conditions that must all match
  • or: Array of conditions where at least one must match
  • not: Negates the contained condition

Each condition is an object with:

  • Field name as key
  • Object containing value or an operator and optional parameters

Operators:

  • ‘value’, ‘is’, ‘equal’: Equal to
  • ‘not_equal’: Not equal to
  • “between”: Value is between two values
  • “greater_than”: Value is greater than
  • “less_than”: Value is less than
  • “greater_than_or_equal”: Value is greater than or equal to
  • “less_than_or_equal”: Value is less than or equal to
  • “is_null”: Value is null
  • “is_not_null”: Value is not null

See the Operators Reference for full information about operators.

Sort Structure

The sort parameter is an array of arrays, where each inner array contains:

  • Field name to sort by
  • Direction (“asc” or “desc”)

Special fields:

  • total_score: Relevance score from search

Response

Returns the created search object as shown in the index response.

HTTP Response Codes

Code Description
201 Created Successful creation
404 Not Found Invalid library ID
422 Unprocessable Entity Invalid request (see response body for details)

GET /api/v1/libraries/{library_id}/searches/{id}

Retrieve details of a specific search.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
id integer ID of the search Yes

Response

Returns the search object as shown in the index response.

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID or search ID