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 lf_your-api-key
Authorization: Bearer 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:

• Pull requests titled "Email login refactor"
• 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 type, contributor, entity, 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: {
      observationTypes: ['pull_request', 'issue'],
      entityTypes: ['repository', 'service'],
      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: {
      observationTypes: ['pull_request', 'issue'],
      entityTypes: ['repository', 'service'],
      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 Can Be Searched?

Lightfast searches workspace memory that your organization has loaded into the platform:

• Decision records, runbooks, and documentation
• Engineering observations and incident notes
• Entities such as services, repositories, projects, and people

Create an organization, add an API key, and use the API or MCP server to query the memory available to that organization.

Next Steps

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