API Overview

The Lightfast API provides memory built for teams. Four simple routes enable you to search by meaning, get full documents, find similar content, and generate answers with citations.

The Four Routes

Base URL

https://api.lightfast.ai/v1

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer lf_sk_live_abc123...

See Authentication for details on API key types and security.

Key Types

Core Principles

Search by Meaning

Unlike keyword search, Lightfast understands intent and context:

{
  "query": "authentication refactor"
}

Finds:

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

Always Cite Sources

Every answer includes citations showing where information came from:

{
  "content": "Authentication uses OAuth 2.0...",
  "citations": [
    {
      "id": "pr-123",
      "title": "Implement OAuth 2.0",
      "url": "https://github.com/org/repo/pull/123"
    }
  ]
}

Explainable by Design

Optional includeRationale parameter shows why results were ranked:

{
  "id": "doc-1",
  "score": 0.89,
  "rationale": "High semantic similarity to query. Recently updated. Owned by auth team."
}

Quick Start

Install SDK

npm install @lightfast/sdk

Initialize Client

import { Lightfast } from '@lightfast/sdk'

const lf = new Lightfast({
  apiKey: process.env.LIGHTFAST_API_KEY
})

Make Your First Call

// Search for content
const results = await lf.search({
  query: 'how does authentication work?',
  limit: 10
})

// Get full content
const docs = await lf.contents({
  ids: [results.data[0].id]
})

// Find similar
const similar = await lf.similar({
  id: results.data[0].id,
  limit: 5
})

// Get answer with citations
const answer = await lf.answer({
  query: 'explain our authentication flow',
  stream: true
})

Rate Limiting

Rate limits vary by plan:

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 542
X-RateLimit-Reset: 1704110400

See Rate Limits Guide for best practices.

Error Handling

All errors follow a consistent format:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 42 seconds.",
  "details": {
    "retryAfter": 42
  },
  "requestId": "req_abc123"
}

Common Error Codes

See Error Reference for complete list and handling strategies.

Response Format

All successful responses follow this structure:

{
  "data": [...],           // Array or object with results
  "meta": {
    "total": 42,           // Total results available
    "limit": 10,           // Results per page
    "offset": 0            // Current offset
  },
  "requestId": "req_abc123"  // Unique request identifier
}

Pagination

Use limit and offset for pagination:

// First page
const page1 = await lf.search({
  query: 'authentication',
  limit: 20,
  offset: 0
})

// Second page
const page2 = await lf.search({
  query: 'authentication',
  limit: 20,
  offset: 20
})

Maximum limit: 100

Filtering

Filter results by metadata:

const results = await lf.search({
  query: 'authentication',
  filters: {
    type: ['pull_request', 'issue'],
    source: 'github',
    createdAfter: '2024-01-01',
    owner: 'auth-team'
  }
})

Available filters vary by your indexed content. See Search for details.

Streaming Responses

The /v1/answer endpoint supports streaming for real-time responses:

const answer = await lf.answer({
  query: 'explain authentication flow',
  stream: true
})

for await (const chunk of answer) {
  process.stdout.write(chunk.content)
}

// Citations arrive in final chunk
console.log('\nSources:', answer.citations)

See Answer for streaming details.

MCP Integration

Lightfast provides MCP (Model Context Protocol) tools for agent integration:

{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfast/mcp-server"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_sk_live_..."
      }
    }
  }
}

See MCP Integration Guide for setup.

What Gets Indexed?

Lightfast automatically indexes:

• GitHub: PRs, issues, discussions, code, wikis
• Linear: Issues, comments, projects
• Notion: Pages, databases
• Slack: Messages, threads (with permissions)
• Discord: Messages, threads
• Custom: Any content via API

See Integrations for setup.

Next Steps

• POST /v1/search - Search by meaning
• POST /v1/contents - Get full documents
• POST /v1/similar - Find related content
• POST /v1/answer - Get answers with citations
• Quickstart - 5-minute guide
• Guides - How-to guides for common tasks