Skip to main content
POST
/
v1
/
collections
/
{readable_id}
/
agentic-search
Agentic Search
curl --request POST \
  --url https://api.example.com/v1/collections/{readable_id}/agentic-search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "mode": "<string>",
  "filter": [
    {}
  ],
  "limit": 123
}
'
{
  "results": [
    {
      "entity_id": "<string>",
      "name": "<string>",
      "relevance_score": 123,
      "textual_representation": "<string>",
      "breadcrumbs": [
        {}
      ],
      "web_url": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "airweave_system_metadata": {},
      "access": {},
      "raw_source_fields": {}
    }
  ],
  "answer": {
    "text": "<string>",
    "citations": [
      {}
    ]
  }
}

Overview

Perform agentic search - an intelligent search system that plans, executes, and evaluates search strategies to find the best results for complex queries. How it works:
  1. Planning: AI analyzes the query and creates a search strategy
  2. Searching: Executes searches with filters and refinements
  3. Evaluation: Assesses result quality and decides whether to continue
  4. Answer Generation: Synthesizes findings into a comprehensive answer
Search Modes:
  • thinking (default): Multi-step intelligent search for complex queries
  • fast: Single-pass search for simple lookups
Feature Requirements:
  • Requires AGENTIC_SEARCH feature flag for your organization
  • Usage is tracked and subject to query limits

Path Parameters

readable_id
string
required
The unique readable identifier of the collection to searchExample: “customer-docs-x7k9m”

Request Body

query
string
required
The natural language search queryExample: “What are the best practices for API key rotation?”
mode
string
default:"thinking"
Search execution mode:
  • thinking: Intelligent multi-step search (may take longer, better results)
  • fast: Single search pass (faster, simpler queries)
filter
array
default:[]
Filter groups always applied to search results. Conditions within a group are combined with AND. Multiple groups are combined with OR.
limit
integer
Maximum number of results to return. The agent may return fewer results based on quality assessment.Minimum: 1

Response

results
array
required
Array of search results ordered by relevance
answer
object
required
AI-generated answer based on search results

Example Request

curl -X POST https://api.airweave.ai/v1/collections/customer-docs-x7k9m/agentic-search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the authentication best practices?",
    "mode": "thinking",
    "limit": 10
  }'

Example Response

{
  "results": [
    {
      "entity_id": "abc123-def456",
      "name": "Authentication Best Practices",
      "relevance_score": 0.95,
      "textual_representation": "# Authentication Best Practices\n\n1. Use API keys with appropriate expiration...\n2. Rotate keys regularly...",
      "breadcrumbs": [
        {"entity_id": "docs-root", "name": "Documentation", "entity_type": "FolderEntity"},
        {"entity_id": "security", "name": "Security", "entity_type": "FolderEntity"}
      ],
      "web_url": "https://github.com/company/docs/blob/main/security/auth.md",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-03-10T14:30:00Z",
      "airweave_system_metadata": {
        "source_name": "GitHub",
        "entity_type": "GitHubFileEntity",
        "sync_id": "sync-123",
        "sync_job_id": "job-456",
        "chunk_index": 0,
        "original_entity_id": "file-789"
      },
      "access": {
        "viewers": null,
        "is_public": true
      },
      "raw_source_fields": {
        "path": "security/auth.md",
        "repo": "company/docs"
      }
    }
  ],
  "answer": {
    "text": "Based on the documentation, here are the key authentication best practices:\n\n1. **API Key Management**: Use API keys with appropriate expiration periods (90-365 days) and rotate them regularly before expiration.\n\n2. **Secure Storage**: Never commit API keys to version control. Store them in secure key management systems.\n\n3. **Regular Rotation**: Implement a key rotation schedule using the rotate endpoint to refresh keys proactively.",
    "citations": [
      {"entity_id": "abc123-def456"},
      {"entity_id": "xyz789-ghi012"}
    ]
  }
}

Performance

  • Fast mode: Typically 1-3 seconds
  • Thinking mode: Typically 5-15 seconds (depends on query complexity)
  • Use fast mode for simple lookups, thinking mode for complex questions

Error Responses

403 Forbidden
AGENTIC_SEARCH feature not enabled for this organization
404 Not Found
Collection with the specified readable_id does not exist
422 Validation Error
Invalid query (empty or invalid parameters)
429 Too Many Requests
Query limit exceeded for your organization