Skip to content

Document Query

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.

Request Body Parameters

Parameter	Type	Required	Description
`bucket_location`	`object`	Yes	The storage bucket containing the target document. Must be an accessible Smart Bucket
`object_id`	`string`	Yes	Document identifier within the bucket. Typically matches the storage path or key
`input`	`string`	Yes	User’s input or question about the document. Can be natural language questions, commands, or requests
`request_id`	`string`	Yes	Client-provided conversation session identifier. Required for maintaining context in follow-up questions. We recommend using a UUID or ULID for this value.

Responses

200

AI-generated response that may include direct document quotes, content summaries, contextual explanations, references to specific sections, and related content suggestions

Returns a DocumentQueryResponse object with the following properties:

Property	Type	Description
`answer`	`string`	AI-generated response that may include direct document quotes, content summaries, contextual explanations, references to specific sections, and related content suggestions

400

Invalid request parameters or malformed request

Returns a Error object with the following properties:

Property	Type	Description
`code`	`integer`	Error code that maps to standard Connect/gRPC error codes
`message`	`string`	Human-readable error message with error code prefix

401

Missing or invalid authentication

Returns a Error object with the following properties:

Property	Type	Description
`code`	`integer`	Error code that maps to standard Connect/gRPC error codes
`message`	`string`	Human-readable error message with error code prefix

403

Insufficient permissions to access the requested resource

Returns a Error object with the following properties:

Property	Type	Description
`code`	`integer`	Error code that maps to standard Connect/gRPC error codes
`message`	`string`	Human-readable error message with error code prefix

404

Requested resource not found

Returns a Error object with the following properties:

Property	Type	Description
`code`	`integer`	Error code that maps to standard Connect/gRPC error codes
`message`	`string`	Human-readable error message with error code prefix

500

Internal server error

Returns a Error object with the following properties:

Property	Type	Description
`code`	`integer`	Error code that maps to standard Connect/gRPC error codes
`message`	`string`	Human-readable error message with error code prefix

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

const client = new Raindrop({
  apiKey: process.env['RAINDROP_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const response = await client.documentQuery.ask({
    bucket_location: { module_id: '01jtgtrd37acrqf7k24dggg31s' },
    input: 'What is the key points in this document?',
    object_id: 'object_id',
    request_id: '123e4567-e89b-12d3-a456-426614174000',
  });

  console.log(response.answer);
}

main();

import os
from lm_raindrop import Raindrop

client = Raindrop(
    api_key=os.environ.get("RAINDROP_API_KEY"),  # This is the default and can be omitted
)
response = client.document_query.ask(
    bucket_location={
        "module_id": "01jtgtrd37acrqf7k24dggg31s"
    },
    input="What is the key points in this document?",
    object_id="object_id",
    request_id="123e4567-e89b-12d3-a456-426614174000",
)
print(response.answer)

package main

import (
  "context"
  "fmt"

  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk"
  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk/option"
)

func main() {
  client := raindrop.NewClient(
    option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RAINDROP_API_KEY")
  )
  response, err := client.DocumentQuery.Ask(context.TODO(), raindrop.DocumentQueryAskParams{
    BucketLocation: raindrop.DocumentQueryAskParamsBucketLocationUnion{
      OfDocumentQueryAsksBucketLocationModuleID: &raindrop.DocumentQueryAskParamsBucketLocationModuleID{
        ModuleID: "01jtgtrd37acrqf7k24dggg31s",
      },
    },
    Input: "What is the key points in this document?",
    ObjectID: "object_id",
    RequestID: "123e4567-e89b-12d3-a456-426614174000",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Answer)
}

package com.raindrop.api.example;

import com.raindrop.api.client.RaindropClient;
import com.raindrop.api.client.okhttp.RaindropOkHttpClient;
import com.raindrop.api.models.documentquery.DocumentQueryAskParams;
import com.raindrop.api.models.documentquery.DocumentQueryAskResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Configures using the `RAINDROP_API_KEY` and `RAINDROP_BASE_URL` environment variables
        RaindropClient client = RaindropOkHttpClient.fromEnv();

        DocumentQueryAskParams params = DocumentQueryAskParams.builder()
            .bucketLocation(DocumentQueryAskParams.BucketLocation.ModuleId.builder()
                .moduleId("01jtgtrd37acrqf7k24dggg31s")
                .build())
            .input("What is the key points in this document?")
            .objectId("object_id")
            .requestId("123e4567-e89b-12d3-a456-426614174000")
            .build();
        DocumentQueryAskResponse response = client.documentQuery().ask(params);
    }
}

# 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

# Query a document in a bucket
curl -X POST https://api.raindrop.run/v1/document_query \
  -H "Authorization: Bearer lm_apikey_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bucket_location": {
      "name": "my-bucket"
    },
    "object_id": "document.pdf",
    "input": "What are the key points in this document?",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

Response Examples

{
  "answer": "The key points in this document are..."
}

Invalid request parameters or malformed request

Examples:

missing-input:

{
  "code": 3,
  "message": "[invalid_argument] Missing required input parameter"
}

missing-request-id:

{
  "code": 3,
  "message": "[invalid_argument] Missing required request_id parameter"
}

invalid-path:

{
  "code": "INVALID_ARGUMENT",
  "message": "Invalid object path"
}

method-not-allowed:

{
  "code": 3,
  "message": "[invalid_argument] Method not allowed"
}

Missing or invalid authentication

Examples:

invalid-auth:

{
  "code": 16,
  "message": "[unauthenticated] Invalid API key"
}

Insufficient permissions to access the requested resource

Examples:

no-bucket-access:

{
  "code": "PERMISSION_DENIED",
  "message": "No access to one or more requested buckets"
}

no-specific-bucket:

{
  "code": "PERMISSION_DENIED",
  "message": "No access to bucket"
}

Requested resource not found

Examples:

not-found:

{
  "code": "NOT_FOUND",
  "message": "Not found"
}

Internal server error

Examples:

internal:

{
  "code": 13,
  "message": "Internal server error"
}