API Overview

The Lightfast API provides memory built for teams. Search by meaning across everything your engineering org produces — pull requests, issues, discussions, docs, and deployments.

Search

Base URL

https://lightfast.ai/api/v1

Authentication

All API requests require one header:

bash
Authorization: Bearer sk-lf-your-api-key
Authorization: Bearer sk-lf-your-api-key

The organization is resolved automatically from the API key. See Authentication for details on obtaining API keys.

Quick Start

Make Your First Call

typescript
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'how does authentication work?',
    limit: 10
  })
})

const results = await response.json()
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'how does authentication work?',
    limit: 10
  })
})

const results = await response.json()

Core Features

Search by Meaning

Unlike keyword search, Lightfast understands intent and context:

json
{
  "query": "authentication refactor"
}
{
  "query": "authentication refactor"
}

Finds:

• PRs titled "Update auth flow for OAuth2"
• Issues about "login security improvements"
• Discussions on "user session management"

Multi-Path Retrieval

Search uses four parallel paths for comprehensive results:

• Vector search: Semantic similarity
• Entity search: Shared entities (people, repos, topics)
• Cluster search: Topic cluster membership
• Actor search: Contributor expertise

Search Modes

Control quality vs. latency with the mode parameter:

Filtering

Filter results by source, type, contributor, or date:

typescript
const results = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'authentication',
    filters: {
      sourceTypes: ['github'],
      observationTypes: ['pull_request', 'issue'],
      actorNames: ['@alice'],
      dateRange: {
        start: '2024-01-01T00:00:00Z'
      }
    }
  })
})
const results = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'authentication',
    filters: {
      sourceTypes: ['github'],
      observationTypes: ['pull_request', 'issue'],
      actorNames: ['@alice'],
      dateRange: {
        start: '2024-01-01T00:00:00Z'
      }
    }
  })
})

See Search for all filter options.

Error Handling

All errors follow a consistent format:

json
{
  "error": "UNAUTHORIZED",
  "message": "Authentication required. Provide 'Authorization: Bearer <api-key>' header or sign in.",
  "requestId": "req_abc123"
}
{
  "error": "UNAUTHORIZED",
  "message": "Authentication required. Provide 'Authorization: Bearer <api-key>' header or sign in.",
  "requestId": "req_abc123"
}

Common Error Codes

See Error Reference for complete list and handling strategies.

What Gets Indexed?

Lightfast indexes content from connected sources:

• GitHub: PRs, issues, commits, discussions
• Linear: Issues, comments, projects
• Vercel: Deployments, logs

Connect sources in the Console settings.

Next Steps

• POST /v1/search — Search by meaning
• Authentication — API key setup
• Errors — Error handling