Skip to content
Raindrop Developer Hub

SmartBucket

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/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"
    }
  }
]

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


const response = await client.query.chunkSearch({
  bucketLocations: [
    { bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' } },
  ],
  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/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>

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


const response = await client.query.documentQuery({
  bucketLocation: {
    bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' },
  },
  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/document_status

Get the indexing status of a document by its object key. This endpoint returns the current indexing status of a document including progress through various processing stages.

Schema Reference

Request Body

bucketLocation (object) Required

Details
Description

The storage bucket containing the target document

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

objectId (string) Required

Details
Description

Document identifier within the bucket (object key)

Example
document.pdf

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


const response = await client.documentStatus.getStatus({
  bucketLocation: {
    bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' },
  },
  objectId: 'document.pdf',
});


console.log(response.embedding);

Response Examples

{
  "status": "processing",
  "ingest": {
    "totalChunksCreated": 123,
    "chunksQueued": 123,
    "creationComplete": true
  },
  "embedding": {
    "totalExpected": 123,
    "itemsRemaining": 123
  },
  "vectorIndex": {
    "totalExpected": 123,
    "itemsRemaining": 123
  },
  "pii": {
    "totalExpected": 123,
    "itemsRemaining": 123
  },
  "relationships": {
    "totalExpected": 123,
    "itemsRemaining": 123
  },
  "errors": [
    "example"
  ]
}

POST /v1/document_status_bulk

Get the indexing status for multiple documents in a single request. This is significantly more efficient than making individual GetDocumentStatus calls, as it searches shards once and returns status for all requested documents.

Schema Reference

Request Body

bucketLocation (object) Required

Details
Description

The storage bucket containing the target documents

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

objectIds (array) Required

Details
Description

List of document identifiers (object keys) to get status for

Example
[
  "document1.pdf",
  "document2.pdf",
  "document3.pdf"
]

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


const response = await client.documentStatusBulk.getStatusBulk({
  bucketLocation: {
    bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' },
  },
  objectIds: ['document1.pdf', 'document2.pdf', 'document3.pdf'],
});


console.log(response.documents);

Response Examples

{
  "documents": [
    {
      "object_id": "doc1.pdf",
      "status": "completed"
    },
    {
      "object_id": "doc2.pdf",
      "status": "processing"
    }
  ]
}

POST /v1/list_objects_by_status

List objects filtered by indexing status. Efficiently queries document storage across all shards to find objects matching (or excluding) specified statuses. Useful for identifying objects that need attention (e.g., failed, processing) or tracking indexing progress.

Schema Reference

Request Body

bucketLocation (object) Required

Details
Description

The storage bucket to query

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

statuses (array) Required

Details
Description

Status values to filter by (e.g., “completed”, “failed”, “processing”, “ingesting”, “partial”, “uploading”, “not_found”)

Example
[
  "failed",
  "processing"
]

exclude (boolean(nullable))

Details
Description

If true, returns objects NOT matching the specified statuses (inverts the filter)

Example
true

prefix (string(nullable))

Details
Description

Optional prefix to filter object keys (e.g., “documents/” to only search in documents folder)

Example
documents/

partition (string(nullable))

Details
Description

Partition to query (defaults to “default”)

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


const client = new Raindrop();


const response = await client.bucket.byStatus.listObjects({
  bucketLocation: {
    bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' },
  },
  statuses: ['failed', 'processing'],
});


console.log(response.documents);

Response Examples

{
  "documents": [
    {
      "object_id": "doc1.pdf",
      "status": "failed",
      "errors": [
        "Embedding service timeout"
      ]
    },
    {
      "object_id": "doc2.pdf",
      "status": "processing"
    }
  ]
}

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"
    }
  }
]

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


const response = await client.query.search({
  bucketLocations: [
    { bucket: { name: 'my-smartbucket', version: '01jxanr45haeswhay4n0q8340y', application_name: 'my-app' } },
  ],
  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

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

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


const client = new Raindrop();


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

Response Examples

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

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>

partition (string(nullable))

Details
Description

Optional partition identifier for multi-tenant data isolation. Defaults to ‘default’ if not specified

Example
tenant-123
 
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..."
}