Search Documents

Perform semantic search across your document library with optional project filtering.

Request Body

Example Request

curl -X POST https://awrag.io/api/v1/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cognitive load theory in education",
    "limit": 10,
    "projectIds": ["abc-123", "def-456"]
  }'

Response (200 OK)

{
  "success": true,
  "data": {
    "results": [
      {
        "chunk_id": "uuid",
        "document_id": "uuid",
        "document_name": "research_paper.pdf",
        "project_id": "uuid",
        "project_name": "Machine Learning Research",
        "content": "Relevant text chunk about machine learning...",
        "chunk_index": 5,
        "similarity_score": 0.87
      }
    ],
    "query": "machine learning",
    "result_count": 5
  }
}

Search Process:

1. Query Analysis: Natural language query processed (with optional multi-concept extraction)
2. Embedding: Query embedded using advanced AI embedding technology (1024-dimensional vectors)
3. Vector Search: Similarity search using pgvector (cosine similarity)
4. Reranking: Results reranked using intelligent semantic reranking
5. Results: Top results returned with rich metadata

Response Fields Explained:

• chunk_id: Unique identifier for the text chunk
• document_id: Source document UUID
• document_name: Original filename
• project_id: Parent project UUID
• project_name: Project name for context
• content: Extracted text chunk (~200 tokens)
• chunk_index: Position in document (0-based)
• similarity_score: Relevance score (0-1, higher is better)
• concepts: (Optional) Array of extracted concepts when multi-concept search is enabled
• concept_count: (Optional) Number of concepts extracted (appears with concepts field)