Skip to content
Raindrop Developer Hub

Query

The query endpoints provide advanced AI-driven search, conversation, and summarization capabilities for documents and media stored in SmartBuckets. It enables users and agents to interact naturally with content through conversational chat (DocumentChat), semantic search (RagSearch), and multi-modal queries across text, images, and audio (document_query). The service also supports intelligent summarization of search results (summarize_page) and paginated result navigation. Designed for seamless integration into AI workflows, these endpoints make complex document exploration, PII detection, and knowledge extraction accessible via simple APIs, eliminating the need for custom pipelines or infrastructure.

POST /v1/document_query

Enables natural conversational interactions with documents stored in SmartBuckets. This endpoint allows users to ask questions, request summaries, and explore document content through an intuitive conversational interface. The system understands context and can handle complex queries about document contents.

The query system maintains conversation context throught the request_id, enabling follow-up questions and deep exploration of document content. It works across all supported file types and automatically handles multi-page documents, making complex file interaction as simple as having a conversation.

The system will:

  • Maintain conversation history for context when using the same request_id
  • Process questions against file content
  • Generate contextual, relevant responses

Document query is supported for all file types, including PDFs, images, and audio files.

Schema Reference

Request Body

bucketLocation (object) Required

Details
Description

The storage bucket containing the target document. Must be a valid, registered Smart Bucket. Used to identify which bucket to query against

Example
{
  "bucket": {
    "name": "my-smartbucket",
    "version": "01jxanr45haeswhay4n0q8340y",
    "application_name": "my-app"
  }
}

objectId (string) Required

Details
Description

Document identifier within the bucket. Typically matches the storage path or key. Used to identify which document to chat with

Example
document.pdf

input (string) Required

Details
Description

User’s input or question about the document. Can be natural language questions, commands, or requests. The system will process this against the document content

Example
What are the key points in this document?

requestId (string) Required

Details
Description

Client-provided conversation session identifier. Required for maintaining context in follow-up questions. We recommend using a UUID or ULID for this value

Example
<YOUR-REQUEST-ID>
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.documentQuery({
  bucketLocation: { bucket: { name: 'my-smartbucket' } },
  input: 'What are the key points in this document?',
  objectId: 'document.pdf',
  requestId: '<YOUR-REQUEST-ID>',
});


console.log(response.answer);

Response Examples

{
  "answer": "Based on the document, the key points are..."
}

POST /v1/chunk_search

Chunk Search provides search capabilities that serve as a complete drop-in replacement for traditional RAG pipelines. This system enables AI agents to leverage private data stored in SmartBuckets with zero additional configuration.

Each input query is processed by our AI agent to determine the best way to search the data. The system will then return the most relevant results from the data ranked by relevance on the input query.

Schema Reference

Request Body

input (string) Required

Details
Description

Natural language query or question. Can include complex criteria and relationships. The system will optimize the search strategy based on this input

Example
Find documents about revenue in Q4 2023

requestId (string) Required

Details
Description

Client-provided search session identifier. Required for pagination and result tracking. We recommend using a UUID or ULID for this value

Example
<YOUR-REQUEST-ID>

bucketLocations (array) Required

Details
Description

The buckets to search. If provided, the search will only return results from these buckets

Example
[
  {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
]
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.chunkSearch({
  bucketLocations: [{ bucket: { name: 'my-smartbucket' } }],
  input: 'Find documents about revenue in Q4 2023',
  requestId: '<YOUR-REQUEST-ID>',
});


console.log(response.results);

Response Examples

{
  "results": [
    {
      "chunkSignature": "chunk_123abc",
      "text": "Sample text",
      "score": 0.95
    }
  ]
}

POST /v1/summarize_page

Generates intelligent summaries of search result pages, helping users quickly understand large result sets without reading through every document. The system analyzes the content of all results on a given page and generates a detailed overview.

The summary system:

  • Identifies key themes and topics
  • Extracts important findings
  • Highlights document relationships
  • Provides content type distribution
  • Summarizes metadata patterns

This is particularly valuable when dealing with:

  • Large document collections
  • Mixed content types
  • Technical documentation
  • Research materials

Schema Reference

Request Body

page (integer) Required

Details
Description

Target page number (1-based)

Example
1

pageSize (integer) Required

Details
Description

Results per page. Affects summary granularity

Example
10

requestId (string) Required

Details
Description

Original search session identifier from the initial search

Example
<YOUR-REQUEST-ID>
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.sumarizePage({ page: 1, pageSize: 10, requestId: '<YOUR-REQUEST-ID>' });


console.log(response.summary);

Response Examples

{
  "summary": "The search results contain information about..."
}

POST /v1/search

Primary search endpoint that provides advanced search capabilities across all document types stored in SmartBuckets.

Supports recursive object search within objects, enabling nested content search like embedded images, text content, and personally identifiable information (PII).

The system supports complex queries like:

  • ‘Show me documents containing credit card numbers or social security numbers’
  • ‘Find images of landscapes taken during sunset’
  • ‘Get documents mentioning revenue forecasts from Q4 2023’
  • ‘Find me all PDF documents that contain pictures of a cat’
  • ‘Find me all audio files that contain information about the weather in SF in 2024’

Key capabilities:

  • Natural language query understanding
  • Content-based search across text, images, and audio
  • Automatic PII detection
  • Multi-modal search (text, images, audio)

Schema Reference

Request Body

input (string) Required

Details
Description

Natural language search query that can include complex criteria. Supports queries like finding documents with specific content types, PII, or semantic meaning

Example
All my files

requestId (string) Required

Details
Description

Client-provided search session identifier. Required for pagination and result tracking. We recommend using a UUID or ULID for this value

Example
<YOUR-REQUEST-ID>

bucketLocations (array) Required

Details
Description

The buckets to search. If provided, the search will only return results from these buckets

Example
[
  {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
]
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.search({
  bucketLocations: [{ bucket: { name: 'my-smartbucket' } }],
  input: 'All my files',
  requestId: '<YOUR-REQUEST-ID>',
});


console.log(response.pagination);

Response Examples

{
  "results": [
    {
      "chunkSignature": "35a494ab4de3ff1157b3cf23e5e94600e24a5552cbb6db645599547075a8c3ad",
      "text": "",
      "source": {
        "bucket": {
          "moduleId": "01jxanr4xbf44jj3p62vwzh8j5",
          "bucketName": "my-smartbucket",
          "applicationVersionId": "01jxanr45haeswhay4n0q8340y",
          "applicationName": "my-app"
        },
        "object": "my-file.pdf"
      }
    }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "totalPages": 10
  }
}

POST /v1/search_get_page

Retrieve additional pages from a previous search. This endpoint enables navigation through large result sets while maintaining search context and result relevance. Retrieving paginated results requires a valid request_id from a previously completed search.

Schema Reference

Request Body

requestId (string) Required

Details
Description

Original search session identifier from the initial search

Example
<YOUR-REQUEST-ID>

page (integer(nullable)) Required

Details
Description

Requested page number

Example
1

pageSize (integer(nullable)) Required

Details
Description

Results per page

Example
10
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


// Automatically fetches more pages as needed.
for await (const queryGetPaginatedSearchResponse of client.query.getPaginatedSearch({
  page: 1,
  pageSize: 10,
  requestId: '<YOUR-REQUEST-ID>',
})) {
  console.log(queryGetPaginatedSearchResponse.chunkSignature);
}

Response Examples

{
  "results": [
    {
      "chunkSignature": "chunk_123abc",
      "text": "Sample text",
      "score": 0.95
    }
  ],
  "pagination": {
    "total": 100,
    "page": 2,
    "pageSize": 10,
    "totalPages": 10
  }
}

POST /v1/answer

Answers a question based on the entire content of a bucket. This combines a chunk search and an LLM to answer the question.

Schema Reference

Request Body

bucketLocation (object) Required

Details
Description

The bucket to search. Must be a valid, registered Smart Bucket.

Example
{
  "bucket": {
    "name": "my-bucket",
    "version": "01jtgtraw3b5qbahrhvrj3ygbb",
    "applicationName": "my-app"
  }
}

input (string) Required

Details
Description

The question to answer.

Example
What is the capital of France?
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const answer = await client.answer.create({
  bucketLocation: { bucket: { name: 'my-bucket' } },
  input: 'What is the capital of France?',
});


console.log(answer.answer);

Response Examples

{
  "answer": "LiquidMetal is a platform for building and deploying serverless applications and AI agents."
}