Airweave Setup & Integration

Airweave is an open-source platform that makes any app searchable for AI agents. It connects to apps, productivity tools, databases, or document stores and transforms their contents into searchable knowledge bases.

Quick Start

Option 1: Airweave Cloud (Recommended)

1. Sign up at https://app.airweave.ai
2. Get your API key from the dashboard
3. Install the SDK:

pip install airweave-sdk   # Python
npm install @airweave/sdk  # TypeScript

Option 2: Self-Hosted

git clone https://github.com/airweave-ai/airweave.git
cd airweave
chmod +x start.sh
./start.sh

Access the dashboard at http://localhost:8080

Core Workflow

The typical Airweave workflow follows these steps:

1. Create a Collection

A collection groups multiple data sources into a single searchable endpoint.

Python:

from airweave import AirweaveSDK

client = AirweaveSDK(
    api_key="YOUR_API_KEY",
    base_url="https://api.airweave.ai"  # or http://localhost:8001 for self-hosted
)

collection = client.collections.create(name="My Knowledge Base")
print(f"Collection ID: {collection.readable_id}")

TypeScript:

import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({ apiKey: "YOUR_API_KEY" });
const collection = await client.collections.create({ name: "My Knowledge Base" });

2. Add Source Connections

Connect data sources to your collection. 40+ sources supported including:

• Productivity: Notion, Google Drive/Docs/Slides, Dropbox, OneDrive, SharePoint, Box, Airtable
• Communication: Slack, Gmail, Outlook, Teams, Google Calendar
• Project Management: Jira, Linear, Asana, Trello, Monday, ClickUp, Todoist
• Development: GitHub, GitLab, Bitbucket, Confluence
• CRM & Sales: Salesforce, HubSpot, Attio, Zendesk, Pipedrive, Shopify
• Data: Stripe, PostgreSQL

See SDK-REFERENCE.md for the complete list of source short names.

Python (API Key sources like Stripe, Linear):

source = client.source_connections.create(
    name="My Stripe Connection",
    short_name="stripe",
    readable_collection_id=collection.readable_id,
    authentication={
        "credentials": {"api_key": "sk_live_your_stripe_key"}
    }
)

OAuth sources (Slack, Google, Microsoft, etc.):

Most sources use OAuth for authentication. Use the Airweave UI at https://app.airweave.ai to connect these sources—it handles the OAuth flow automatically.

3. Search Your Data

Once synced, search across all connected sources with a single query:

Python:

results = client.collections.search(
    readable_id=collection.readable_id,
    query="customer feedback about pricing"
)

for result in results.results:
    print(f"Source: {result['payload']['source_name']}")
    print(f"Content: {result['payload']['md_content'][:200]}...")
    print(f"Score: {result['score']}")

Advanced Search Features

Airweave provides powerful search capabilities:

Search Parameters

Parameter	Type	Description
query	string	Natural language search query
search_type	"semantic" | "hybrid"	Semantic (default) or hybrid search
limit	number	Max results (default: 100)
offset	number	Skip results for pagination
recency_bias	0-1	Prioritize recent results (0=none, 1=most recent)
enable_reranking	boolean	AI reranking for better relevance
enable_query_expansion	boolean	Expand query with variations
response_type	"raw" | "completion"	Raw results or AI-generated answer
top_k	number	Internal retrieval count before reranking

Example: Advanced Search

results = client.collections.search(
    readable_id=collection.readable_id,
    query="technical documentation",
    search_type="hybrid",
    enable_query_expansion=True,
    enable_reranking=True,
    recency_bias=0.5,
    top_k=50,
    limit=20
)

Example: AI-Generated Answer

answer = client.collections.search(
    readable_id=collection.readable_id,
    query="What are our customer refund policies?",
    response_type="completion",
    enable_reranking=True
)
# Returns a synthesized answer instead of raw results

MCP Integration for AI Agents

Airweave exposes search via MCP (Model Context Protocol) for seamless AI agent integration.

Setup for Claude Desktop / Cursor

Add to your MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "airweave-search": {
      "command": "npx",
      "args": ["airweave-mcp-search"],
      "env": {
        "AIRWEAVE_API_KEY": "your-api-key",
        "AIRWEAVE_COLLECTION": "your-collection-id",
        "AIRWEAVE_BASE_URL": "https://api.airweave.ai"
      }
    }
  }
}

Hosted MCP Server

For cloud-based AI platforms like OpenAI Agent Builder:

• URL: https://mcp.airweave.ai
• Uses Streamable HTTP transport (MCP 2025-03-26)

See MCP-SETUP.md for detailed configuration.

Common Patterns

Pattern 1: Search with Source Filtering

from airweave import SearchRequest, Filter, FieldCondition, MatchAny

search_request = SearchRequest(
    query="project updates",
    filter=Filter(
        must=[
            FieldCondition(
                key="source_name",
                match=MatchAny(any=["Slack", "GitHub"])
            )
        ]
    )
)

results = client.collections.search_advanced(
    readable_id=collection.readable_id,
    search_request=search_request
)

Pattern 2: Recent Documents First

results = client.collections.search(
    readable_id=collection.readable_id,
    query="critical bugs",
    recency_bias=0.8,  # Strongly prefer recent
    limit=10
)

Pattern 3: High-Quality Results with Reranking

results = client.collections.search(
    readable_id=collection.readable_id,
    query="API documentation",
    enable_reranking=True,
    top_k=30,
    limit=10
)

Troubleshooting

No Results Found

• Check that sync has completed (can take a few minutes for large sources)
• Verify the collection ID is correct
• Try a broader search query

Authentication Errors

• Verify your API key is valid
• Check that the API key has access to the collection
• For OAuth sources, the token may have expired—reconnect in the UI

Rate Limits

• The API has rate limits for protection
• Implement exponential backoff for retries
• Contact support for higher limits

Additional Resources

• Documentation: https://docs.airweave.ai
• API Reference: https://api.airweave.ai/docs (Swagger)
• GitHub: https://github.com/airweave-ai/airweave
• Discord: https://discord.gg/484HY9Ehxt

For detailed SDK reference, see SDK-REFERENCE.md. For advanced search patterns, see SEARCH-PATTERNS.md.