Search

The Search API lets you query indexed data across your collections using semantic search, keyword matching, or a combination of both.

Endpoints

POST /api/v1/search

Full-featured search with all parameters.

Request:

curl -X POST https://api.ballast.sh/v1/search 
  -H "Authorization: Bearer bk_your_api_key" 
  -H "Content-Type: application/json" 
  -d '{
    "collectionId": "col_abc123",
    "query": "remote work policy",
    "limit": 10,
    "rerank": true,
    "generateAnswer": true
  }'

Parameters:

Field	Type	Required	Description
collectionId	string	Yes	Collection UUID to search
query	string	Yes	Search query
limit	int	No	Max results (default: 10)
filters	array	No	Metadata filters
rerank	bool	No	Apply LLM reranking
expandQuery	bool	No	Generate query variations
generateAnswer	bool	No	Synthesize answer from results

Response:

{
  "success": true,
  "results": [
    {
      "id": "doc_123",
      "score": 0.92,
      "content": "Our remote work policy allows...",
      "metadata": {
        "source": "notion",
        "title": "Company Policies",
        "url": "https://..."
      }
    }
  ],
  "query": "remote work policy",
  "answer": "The company's remote work policy allows employees to work from home up to 3 days per week...",
  "took": 245
}

GET /api/v1/collections/:id/search

Simpler search endpoint with query parameters.

Request:

curl "https://api.ballast.sh/v1/collections/col_abc123/search?query=remote%20work&limit=10" 
  -H "Authorization: Bearer bk_your_api_key"

Parameters:

Field	Type	Required	Description
id	string	Yes	Collection ID (path parameter)
query	string	Yes	Search query
responseType	string	No	raw (default) or completion
limit	int	No	Max results (default: 10)

Response Types:

• raw: Returns search results only
• completion: Returns results plus an AI-generated answer

Search Results

Each result includes:

Field	Description
id	Unique document/chunk identifier
score	Relevance score (0-1)
content	Matched content snippet
metadata	Source-specific metadata

Common Metadata Fields

Field	Description
source	Source type (slack, notion, gdrive, etc.)
title	Document or message title
url	Link to original content
author	Content author
created_at	Creation timestamp
updated_at	Last update timestamp

Filters

Apply metadata filters to narrow results:

{
  "collectionId": "col_abc123",
  "query": "budget",
  "filters": [
    {
      "field": "source",
      "operator": "eq",
      "value": "gsheets"
    },
    {
      "field": "created_at",
      "operator": "gte",
      "value": "2024-01-01"
    }
  ]
}

Operators:

Operator	Description
eq	Equals
neq	Not equals
gt	Greater than
gte	Greater than or equal
lt	Less than
lte	Less than or equal
in	In array
contains	Contains substring

Search Features

Query Expansion

When expandQuery: true, Ballast generates semantic variations of your query to improve recall:

{
  "query": "remote work policy",
  "expandQuery": true
}

For “remote work policy”, might also search for:

• “work from home guidelines”
• “distributed team rules”
• “telecommuting policy”

Reranking

When rerank: true, results are reordered using an LLM for better relevance:

{
  "query": "budget approval process",
  "rerank": true
}

Reranking uses Cohere or Jina models to evaluate semantic relevance beyond vector similarity.

Answer Generation

When generateAnswer: true, an LLM synthesizes an answer from the top results:

{
  "query": "What is the vacation policy?",
  "generateAnswer": true
}

Response includes:

{
  "results": [...],
  "answer": "The vacation policy provides 20 days of PTO annually, plus..."
}

Error Responses

Status	Error	Description
400	invalid_request	Missing required fields
401	unauthorized	Invalid or missing authentication
403	forbidden	No access to collection
404	not_found	Collection doesn’t exist
500	search_failed	Internal search error

Best Practices

Keep queries focused

• Short, specific queries often work better than long ones
• Use filters to narrow scope instead of adding terms

Use filters for structured data

• Filter by source, date, author for precise results
• Combine multiple filters for complex queries

Enable reranking for quality

• Reranking improves relevance but adds latency
• Best for user-facing searches where quality matters

Use answer generation sparingly

• Only enable when you need synthesized answers
• Adds significant latency and token usage

Handle empty results gracefully

• Check results.length before processing
• Consider suggesting alternative queries