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)

Sign up at https://app.airweave.ai
Get your API key from the dashboard
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. Airweave provides three search modes:

Mode	Description	Best For
`instant`	Direct vector search	Fast lookups, browsing
`classic`	AI-optimized search with LLM-generated search plans	Most searches (default)
`agentic`	Full agent loop with iterative reasoning	Complex questions, analysis

Python:

# Classic search (default) — AI-optimized
results = client.collections.search(
    readable_id=collection.readable_id,
    query="customer feedback about pricing",
    mode="classic"
)

for result in results.results:
    print(f"Source: {result.airweave_system_metadata.source_name}")
    print(f"Name: {result.name}")
    print(f"Content: {result.textual_representation[:200]}...")
    print(f"Score: {result.relevance_score}")
    print(f"URL: {result.web_url}")

Search Modes in Detail

Instant Search

Fast, direct vector search. Best for simple lookups.

results = client.collections.search(
    readable_id=collection.readable_id,
    query="API documentation",
    mode="instant",
    retrieval_strategy="hybrid",  # "hybrid" (default), "neural", or "keyword"
    limit=20,
    offset=0
)

Classic Search

AI generates an optimized search plan. Best general-purpose mode.

results = client.collections.search(
    readable_id=collection.readable_id,
    query="technical documentation",
    mode="classic",
    limit=20,
    offset=0
)

Agentic Search

Full agent loop that iteratively searches, reads, and reasons over results.

results = client.collections.search(
    readable_id=collection.readable_id,
    query="Summarize all decisions about the authentication redesign",
    mode="agentic",
    thinking=True,  # Enable extended reasoning
    limit=10
)

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.

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
Try a different search mode (e.g., classic instead of instant)

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.

airweave-setup