Quickstart

Connect your first data source and start searching in under 5 minutes.

Get up and running with Ballast in minutes. By the end of this guide, you’ll have connected a data source and run your first semantic search.

1. Create an Account

Sign up at app.ballast.sh/signup. The free tier includes enough usage to explore all features.

2. Create a Collection

Collections are the core unit in Ballast. Each collection is a searchable index that can contain data from multiple sources.

  1. From the dashboard, click New Collection
  2. Give it a name (e.g., “Company Knowledge Base”)
  3. Click Create

3. Connect a Data Source

With your collection created, add a data source:

  1. Click Add Source in your collection
  2. Choose from 57 integrations (Google Drive, Slack, Notion, PostgreSQL, etc.)
  3. For OAuth sources, click Connect and authorize access
  4. For databases, enter your connection credentials
  5. Configure what to sync (folders, channels, tables, etc.)

Ballast begins syncing immediately. You’ll see progress in the Sources panel. For most sources, initial sync takes 2-10 minutes depending on data volume.

4. Run a Search

Once syncing completes, use the Search interface:

What were the key decisions from our last planning meeting?

Ballast returns semantically relevant results from all connected sources, ranked by relevance. Each result shows the source, document title, and a snippet.

5. Try the Chat Interface

The Chat interface goes beyond search—it synthesizes information and can generate visualizations:

Show me a breakdown of our support tickets by category

Ballast searches your indexed data, analyzes it, and generates charts. Save useful analyses as dashboards to share with your team.

6. Get API Access

For programmatic access or AI agent integration, create an API key:

  1. Go to Settings → API Keys in your collection
  2. Click Create API Key
  3. Name it and copy the key—it’s shown only once

Test with a search request:

curl -X POST https://api.ballast.sh/v1/search 
  -H "Authorization: Bearer bk_your_api_key" 
  -H "Content-Type: application/json" 
  -d '{"query": "planning decisions", "collectionId": "your_collection_id"}'

7. Connect Claude via MCP

Each collection exposes a Model Context Protocol (MCP) server. Claude Desktop can connect directly to search your data:

  1. Get your collection’s MCP URL from Settings → MCP
  2. Add it to Claude Desktop’s config
  3. Claude can now search your collection during conversations

See MCP Setup for detailed instructions.

Next Steps