Search Collection

Search your collection using semantic and hybrid search

POST /v1/collections/{readable_id}/search

Search Collection

cURL

curl --request POST \
  --url https://api.example.com/v1/collections/{readable_id}/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "retrieval_strategy": "<string>",
  "filter": {},
  "offset": 123,
  "limit": 123,
  "expand_query": true,
  "interpret_filters": true,
  "rerank": true,
  "generate_answer": true
}
'

200

{
  "results": [
    {
      "entity_id": "<string>",
      "source_name": "<string>",
      "md_content": "<string>",
      "metadata": {},
      "score": 123,
      "breadcrumbs": [
        {}
      ],
      "url": "<string>"
    }
  ],
  "completion": "<string>"
}

Overview

Search your collection using AI-powered semantic search. This endpoint provides powerful search capabilities:

Search Strategies:

• hybrid (default): Combines neural (semantic) and keyword (BM25) matching
• neural: Pure semantic search using embeddings
• keyword: Traditional keyword-based BM25 search

Features:

• Query expansion: Generate query variations to improve recall
• Filter interpretation: Extract structured filters from natural language
• Reranking: LLM-based reranking for improved relevance
• Answer generation: AI-generated answers based on search results

Path Parameters

readable_id · string · required

The unique readable identifier of the collection to search

Request Body

query · string · required

The search query text (max 2048 tokens)

Example: “How do I reset my password?”

retrieval_strategy · string · default: "hybrid"

Search strategy: hybrid, neural, or keyword

filter · object

Structured filter for metadata-based filtering (Qdrant filter format)

Show example

{
  "must": [
    {"key": "source_name", "match": {"value": "GitHub"}}
  ]
}

offset · integer · default: 0

Number of results to skip for pagination

limit · integer · default: 10

Maximum number of results to return (1-1000)

expand_query · boolean · default: true

Generate query variations to improve recall

interpret_filters · boolean · default: false

Extract structured filters from natural language (e.g., ‘from last week’)

rerank · boolean · default: true

Apply LLM-based reranking for improved relevance

generate_answer · boolean · default: true

Generate an AI answer based on search results

Response

results · array · required

Array of search result objects

Show result properties

entity_id · string

Unique identifier of the matched entity

source_name · string

Source that this result came from (e.g., “GitHub”, “Slack”)

md_content · string

Markdown content of the result

metadata · object

Source-specific metadata

score · number

Relevance score (0-1)

breadcrumbs · array

Hierarchical path to the result

url · string

Direct link to the original source

completion · string

AI-generated answer based on search results (only if generate_answer: true)

Example Request

cURL

curl -X POST https://api.airweave.ai/v1/collections/customer-support-tickets-x7k9m/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I reset my password?",
    "limit": 10
  }'

Example Response

{
  "results": [
    {
      "entity_id": "abc123-def456-789012",
      "source_name": "GitHub",
      "md_content": "# Password Reset Guide\n\nTo reset your password...",
      "metadata": {
        "file_path": "docs/auth/password-reset.md",
        "last_modified": "2024-03-15T09:30:00Z"
      },
      "score": 0.92,
      "breadcrumbs": ["docs", "auth", "password-reset.md"],
      "url": "https://github.com/company/docs/blob/main/docs/auth/password-reset.md"
    }
  ],
  "completion": "To reset your password, navigate to the login page and click 'Forgot Password'. You'll receive an email with a reset link that expires in 24 hours."
}

Error Responses

404 Not Found

Collection with the specified readable_id does not exist

422 Validation Error

Invalid query (e.g., exceeds token limit)