Search Code

Perform semantic search across your indexed codebases.

Endpoint

POST /queries/search/:repoId

Path Parameters

Parameter	Type	Required	Description
repoId	string	✅ Yes	Repository identifier to search within

Request Body

Parameter	Type	Required	Default	Description
prompt	string	✅ Yes	-	Natural language search query
k	number	No	5	Number of results (max: 100)
meta	object	No	-	Additional metadata filters

Example Request

curl -X POST http://localhost:3000/queries/search/nest \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How does authentication work?",
    "k": 5
  }'

Response

{
  "results": [
    {
      "id": "src/auth/auth.service.ts",
      "content": "import { Injectable } from '@nestjs/common';\n\n@Injectable()\nexport class AuthService {\n  // Full file content...\n}",
      "repoId": "nest",
      "metadata": {
        "team": "backend",
        "category": "repository"
      }
    },
    {
      "id": "src/auth/guards/jwt.guard.ts",
      "content": "export class JwtAuthGuard extends AuthGuard('jwt') {\n  // ...\n}",
      "repoId": "nest",
      "metadata": {
        "team": "backend",
        "category": "repository"
      }
    }
  ]
}

Response Fields

Field	Type	Description
results	array	Array of matching chunk objects
results[].id	string	File path (e.g., src/auth/auth.service.ts)
results[].content	string	Full file content
results[].repoId	string	Repository identifier
results[].metadata	object	Custom metadata from ingestion

How It Works

1. Your prompt is converted to a vector embedding
2. ChromaDB performs similarity search on child chunks
3. Matching chunks are grouped by parent document
4. Full parent document content is returned

Parent-Child Retrieval

• The k parameter is multiplied by 3 internally
• This searches 3× more child chunks than results requested
• Ensures diverse, high-quality parent documents

Metadata Filtering

Filter results using custom metadata in the request body:

curl -X POST http://localhost:3000/queries/search/backend-api \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Database connection pooling",
    "k": 5,
    "meta": { 
      "team": "platform",
      "environment": "production"
    }
  }'

Filter Logic

Multiple metadata filters are combined with AND logic. All specified filters must match.

Query Examples

Basic Search

curl -X POST http://localhost:3000/queries/search/my-repo \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How is database connection pooling implemented?",
    "k": 5
  }'

Search with Metadata Filters

curl -X POST http://localhost:3000/queries/search/backend-api \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How are API errors formatted?",
    "k": 10,
    "meta": {
      "team": "platform",
      "environment": "production"
    }
  }'

Find Tests

curl -X POST http://localhost:3000/queries/search/auth-service \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What unit tests exist for the user service?",
    "k": 10
  }'

Query Best Practices

❌ Avoid	✅ Better
"auth"	"How does user authentication work?"
"database"	"Where is the database connection configured?"
"error"	"How are API errors formatted and returned?"

Status Codes

Code	Description
200	Search completed
400	Invalid query parameters
404	Repository not found
500	Search failed