Log In

POST /v1/search

Search across all your indexed content using semantic understanding. Returns ranked results with optional context about related topics and experts.

Endpoint

POST https://lightfast.ai/api/v1/search

Authentication

See Authentication for details.

bash
Authorization: Bearer YOUR_API_KEY
X-Workspace-ID: ws_abc123

Request Body

typescript
{
  query: string              // Search query (required)
  limit?: number             // Results to return (1-100, default: 10)
  offset?: number            // Pagination offset (default: 0)
  mode?: "fast" | "balanced" | "thorough"  // Rerank mode (default: "balanced")
  filters?: {
    sourceTypes?: string[]   // Filter by source (e.g., ["github", "linear"])
    observationTypes?: string[] // Filter by type (e.g., ["commit", "issue"])
    actorNames?: string[]    // Filter by contributor (e.g., ["@sarah"])
    dateRange?: {
      start?: string         // ISO 8601 datetime
      end?: string           // ISO 8601 datetime
    }
  }
  includeContext?: boolean   // Include clusters and actors (default: true)
  includeHighlights?: boolean // Include highlighted snippets (default: true)
}

Search Modes

ModeDescriptionTypical Latency
fastVector scores only, no reranking~50ms
balancedCohere reranking for quality~130ms
thoroughLLM-based scoring for best results~600ms

Response

typescript
{
  data: Array<{
    id: string               // Observation ID
    title: string            // Content title
    url: string              // Link to source
    snippet: string          // Content preview
    score: number            // Relevance score (0-1)
    source: string           // Source type (github, linear, etc.)
    type: string             // Observation type (commit, issue, etc.)
    occurredAt?: string      // When the event occurred (ISO 8601)
    entities?: Array<{       // Extracted entities
      key: string
      category: string
    }>
    highlights?: {           // Highlighted matches
      title?: string
      snippet?: string
    }
  }>
  context?: {
    clusters?: Array<{       // Related topic clusters
      topic: string | null
      summary: string | null
      keywords: string[]
    }>
    relevantActors?: Array<{ // Relevant contributors
      displayName: string
      expertiseDomains: string[]
    }>
  }
  meta: {
    total: number            // Total matching results
    limit: number            // Results per page
    offset: number           // Current offset
    took: number             // Total time in ms
    mode: string             // Rerank mode used
    paths: {                 // Search paths executed
      vector: boolean
      entity: boolean
      cluster: boolean
      actor: boolean
    }
  }
  latency: {
    total: number            // Total request latency
    auth?: number            // Authentication time
    parse?: number           // Request parsing
    search?: number          // Total search time
    embedding?: number       // Embedding generation
    retrieval: number        // Vector retrieval
    entitySearch?: number    // Entity path search
    clusterSearch?: number   // Cluster path search
    actorSearch?: number     // Actor path search
    rerank: number           // Reranking time
    enrich?: number          // Database enrichment
    maxParallel?: number     // Bottleneck parallel operation
  }
  requestId: string          // Request ID for debugging
}

Example Request

bash
curl -X POST https://lightfast.ai/api/v1/search \
  -H "Authorization: Bearer $LIGHTFAST_API_KEY" \
  -H "X-Workspace-ID: $LIGHTFAST_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does authentication work?",
    "limit": 10,
    "mode": "balanced",
    "filters": {
      "sourceTypes": ["github"],
      "observationTypes": ["pull_request", "issue"]
    },
    "includeContext": true,
    "includeHighlights": true
  }'

Example Response

json
{
  "data": [
    {
      "id": "obs_abc123",
      "title": "Implement OAuth 2.0 authentication",
      "url": "https://github.com/org/repo/pull/123",
      "snippet": "Added OAuth 2.0 authentication flow with refresh tokens and JWT validation...",
      "score": 0.92,
      "source": "github",
      "type": "pull_request",
      "occurredAt": "2024-03-15T10:30:00Z",
      "entities": [
        { "key": "OAuth 2.0", "category": "technology" },
        { "key": "JWT", "category": "technology" }
      ],
      "highlights": {
        "title": "Implement <mark>OAuth 2.0 authentication</mark>",
        "snippet": "Added <mark>OAuth 2.0 authentication</mark> flow with refresh tokens..."
      }
    },
    {
      "id": "obs_def456",
      "title": "Security: Review authentication flow",
      "url": "https://github.com/org/repo/issues/456",
      "snippet": "We should review the current authentication implementation...",
      "score": 0.87,
      "source": "github",
      "type": "issue",
      "occurredAt": "2024-02-20T09:15:00Z"
    }
  ],
  "context": {
    "clusters": [
      {
        "topic": "Authentication & Security",
        "summary": "OAuth implementation, JWT tokens, and security reviews",
        "keywords": ["oauth", "jwt", "authentication", "security"]
      }
    ],
    "relevantActors": [
      {
        "displayName": "Alice Chen",
        "expertiseDomains": ["authentication", "security", "backend"]
      }
    ]
  },
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "took": 127,
    "mode": "balanced",
    "paths": {
      "vector": true,
      "entity": true,
      "cluster": true,
      "actor": true
    }
  },
  "latency": {
    "total": 127,
    "auth": 2,
    "parse": 1,
    "search": 85,
    "embedding": 15,
    "retrieval": 45,
    "entitySearch": 30,
    "clusterSearch": 25,
    "actorSearch": 20,
    "rerank": 35,
    "enrich": 4,
    "maxParallel": 45
  },
  "requestId": "req_abc123def456"
}

Filtering

By Source Type

Filter to specific sources:

typescript
filters: {
  sourceTypes: ["github", "linear"]  // Only GitHub and Linear
}

By Observation Type

Filter to specific content types:

typescript
filters: {
  observationTypes: ["pull_request", "issue", "commit"]
}

Common observation types:

  • pull_request - Code changes
  • issue - Bug reports, feature requests
  • commit - Individual commits
  • discussion - Threaded conversations
  • document - Documentation

By Contributor

Filter by who created the content:

typescript
filters: {
  actorNames: ["@alice", "@bob"]
}

By Date Range

Filter to a time period:

typescript
filters: {
  dateRange: {
    start: "2024-01-01T00:00:00Z",
    end: "2024-12-31T23:59:59Z"
  }
}

Combined Filters

Combine multiple filters:

typescript
filters: {
  sourceTypes: ["github"],
  observationTypes: ["pull_request"],
  actorNames: ["@alice"],
  dateRange: {
    start: "2024-06-01T00:00:00Z"
  }
}

Pagination

Use limit and offset for pagination:

typescript
// First page
const page1 = await fetch('/v1/search', {
  body: JSON.stringify({
    query: 'authentication',
    limit: 20,
    offset: 0
  })
})

// Second page
const page2 = await fetch('/v1/search', {
  body: JSON.stringify({
    query: 'authentication',
    limit: 20,
    offset: 20
  })
})

// Check for more pages
const hasMore = response.meta.offset + response.meta.limit < response.meta.total

Understanding Context

When includeContext: true, the response includes:

Clusters

Topic clusters help you understand related themes:

typescript
response.context?.clusters?.forEach(cluster => {
  console.log('Topic:', cluster.topic)
  console.log('Summary:', cluster.summary)
  console.log('Keywords:', cluster.keywords.join(', '))
})

Relevant Actors

Find experts on the topic:

typescript
response.context?.relevantActors?.forEach(actor => {
  console.log('Expert:', actor.displayName)
  console.log('Domains:', actor.expertiseDomains.join(', '))
})

Understanding Latency

The latency object breaks down where time is spent:

FieldDescription
totalEnd-to-end request time
embeddingTime to generate query embedding
retrievalVector search time
entitySearchEntity-based retrieval
clusterSearchCluster-based retrieval
actorSearchActor-based retrieval
rerankReranking model time
maxParallelBottleneck of parallel operations

The maxParallel field shows the slowest parallel operation, which determines the total search phase duration.

Error Handling

typescript
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Workspace-ID': workspaceId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'authentication' })
})

if (!response.ok) {
  const error = await response.json()
  console.error('Search failed:', error.error, error.message)
}

See Error Reference for all error codes.

Next Steps

On this page

POST /v1/searchEndpointAuthenticationRequest BodySearch ModesResponseExample RequestExample ResponseFilteringBy Source TypeBy Observation TypeBy ContributorBy Date RangeCombined FiltersPaginationUnderstanding ContextClustersRelevant ActorsUnderstanding LatencyError HandlingNext Steps