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

liquidmetal.v1alpha1.DocumentChatRequest

bucket_location (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-bucket",
    "version": "01jtgtraw3b5qbahrhvrj3ygbb",
    "application_name": "my-app"
  }
}

object_id (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?

request_id (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
123e4567-e89b-12d3-a456-426614174000
Terminal window
# Query a document in a bucket
npx raindrop query document "What are the key points in this document?" \
  -b my-bucket \
  --object-id document.pdf

Response Examples

{
  "answer": "The key points in this document 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

liquidmetal.v1alpha1.RagSearchRequest

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

request_id (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
123e4567-e89b-12d3-a456-426614174000

bucket_locations (array) Required

Details
Description

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

Example
[
  {
    "bucket": {
      "name": "my-bucket",
      "version": "01jtgtraw3b5qbahrhvrj3ygbb",
      "application_name": "my-app"
    }
  }
]
Terminal window
# Run a RAG search query
npx raindrop query chunk-search "What is LiquidMetal?" -b my-bucket

Response Examples

{
  "results": [
    {
      "chunk_signature": "b828de4f5f109b543b201a9f6a17ea5107334fe48f55922ece67790b4a0e1da7",
      "text": "United States Depament of Agriculhlre Animal and Plat Heanh lmpedion Service W S E Y 4042 cust-id 260223 insp-id 1451 site-id SHARON GRAVES Customer 10: 4042 ROCK CREEK KENNEL Certificate: 7sA-0568 Site: 001 SHARON GRAVES Inspection Type: ROUTINE INSPECTION Date: NOV-16-2005",
      "source": {
        "$typeName": "liquidmetal.v1alpha1.SourceResult",
        "object": "bucketHawk.png",
        "bucket": {
          "$typeName": "liquidmetal.v1alpha1.BucketResponse",
          "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84",
          "bucketName": "mr-bucket",
          "applicationVersionId": "01jt3vs1qggsy39eeyq4k295q1",
          "applicationName": "demo-smartbucket"
        }
      },
      "payload_signature": "e2ec3b118e205ff5d627e0c866224a25ba52e6d3ab758a3ef3d49e80908d7444",
      "score": 0.5829625306758838,
      "type": "application/pdf"
    },
    {
      "chunk_signature": "19eb748962554928015f94c5aacf578170e4c90e24d8f716496ad3b11bbe9730",
      "text": "Water. Do not use tap water or mineral water on carnivorous plants. Rainwater, melted snow or distilled water are ideal.",
      "source": {
        "$typeName": "liquidmetal.v1alpha1.SourceResult",
        "object": "bucketHawk.png",
        "bucket": {
          "$typeName": "liquidmetal.v1alpha1.BucketResponse",
          "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84",
          "bucketName": "mr-bucket",
          "applicationVersionId": "01jt3vs1qggsy39eeyq4k295q1",
          "applicationName": "demo-smartbucket"
        }
      },
      "payload_signature": "e3b1df864490efc4c9bcf51acbab69c162a49d8764dc789afd04bd8e90d6681d",
      "score": 0.5772775931035213,
      "type": "application/pdf"
    }
  ]
}

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

liquidmetal.v1alpha1.CreatePageSummaryRequest

page (integer) Required

Details
Description

Target page number (1-based)

Example
1

page_size (integer) Required

Details
Description

Results per page. Affects summary granularity

Example
10

request_id (string) Required

Details
Description

Original search session identifier from the initial search

Example
123e4567-e89b-12d3-a456-426614174000
Terminal window
# coming soon!

Response Examples

{
  "summary": "# Results Summary\n\n* ...."
}

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

liquidmetal.v1alpha1.RunSupervisorAgentRequest

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
Show me documents containing credit card numbers or social security numbers

request_id (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
123e4567-e89b-12d3-a456-426614174000

bucket_locations (array) Required

Details
Description

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

Example
[
  {
    "bucket": {
      "name": "my-bucket",
      "version": "01jtgtraw3b5qbahrhvrj3ygbb",
      "application_name": "my-app"
    }
  }
]
Terminal window
# Run a new search query
npx raindrop query search "Find documents about revenue in Q4 2023" -b customer-data


# Get paginated results using request ID
npx raindrop query search --requestId 01HNG4V2RJXS5T --page 2

Response Examples

{
  "results": [
    {
      "chunk_signature": "51abb575a5e438a2db5fa064611995dfd76aa14d9e4b2a44c29a6374203126a5",
      "text": "",
      "source": {
        "$typeName": "liquidmetal.v1alpha1.SourceResult",
        "object": "bucketHawk.png",
        "bucket": {
          "$typeName": "liquidmetal.v1alpha1.BucketResponse",
          "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84",
          "bucketName": "mr-bucket",
          "applicationVersionId": "01jt3vs1qggsy39eeyq4k295q1",
          "applicationName": "demo-smartbucket"
        }
      },
      "payload_signature": "51abb575a5e438a2db5fa064611995dfd76aa14d9e4b2a44c29a6374203126a5",
      "score": 0,
      "type": "application/pdf"
    },
    {
      "chunk_signature": "9b3ad44c6a308f34bb250696041647ef9f1bcac896eeb25f027de755eaeb8b2c",
      "text": "",
      "source": {
        "$typeName": "liquidmetal.v1alpha1.SourceResult",
        "object": "bucketHawk.png",
        "bucket": {
          "$typeName": "liquidmetal.v1alpha1.BucketResponse",
          "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84",
          "bucketName": "mr-bucket",
          "applicationVersionId": "01jt3vs1qggsy39eeyq4k295q1",
          "applicationName": "demo-smartbucket"
        }
      },
      "payload_signature": "9b3ad44c6a308f34bb250696041647ef9f1bcac896eeb25f027de755eaeb8b2c",
      "score": 0,
      "type": "application/pdf"
    }
  ],
  "pagination": {
    "total": 1020,
    "page": 1,
    "page_size": 15,
    "total_pages": 68,
    "has_more": true
  }
}