Skip to main content
POST
/
knowledge
/
search
Search through all files in data folders shared with the API Key
curl --request POST \
  --url https://api.langdock.com/knowledge/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "API Documentation"
}
'
Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public
Performs a semantic search across all knowledge folders shared with your API key. Returns relevant document chunks ranked by similarity to your query.
Requires an API key with the KNOWLEDGE_FOLDER_API scope. The search is scoped to all knowledge folders shared with the API key. See Share Knowledge Folders with the API for setup instructions.

​
How It Works

  1. Your query is converted to an embedding using your workspace’s default embedding model
  2. The system performs vector similarity search across all documents in shared knowledge folders
  3. Results are filtered by relevance threshold and re-ranked using an LLM
  4. Only the highest-scoring chunk per document is returned

​
Request Format

​
Request Body

ParameterTypeRequiredDescription
querystringYesThe search query to find relevant documents

​
Examples

​
Search with cURL

curl -X POST "https://api.langdock.com/knowledge/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the Q4 revenue projections?"}'

​
Search with JavaScript

const axios = require("axios");

async function searchKnowledge(query) {
  const response = await axios.post(
    "https://api.langdock.com/knowledge/search",
    { query },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  return response.data;
}

// Example usage
const results = await searchKnowledge("What are the Q4 revenue projections?");
console.log(`Found ${results.result.length} relevant documents`);

results.result.forEach((chunk, i) => {
  console.log(`\n--- Result ${i + 1} ---`);
  console.log(`File: ${chunk.subname}`);
  console.log(`Similarity: ${(chunk.similarity * 100).toFixed(1)}%`);
  console.log(`Text: ${chunk.text.substring(0, 200)}...`);
});

​
Using Search Results for RAG

async function answerWithContext(question) {
  // Search for relevant context
  const searchResults = await searchKnowledge(question);

  // Build context from search results
  const context = searchResults.result
    .map((chunk) => `Source: ${chunk.subname}\n${chunk.text}`)
    .join("\n\n---\n\n");

  // Use context with your LLM
  const prompt = `Based on the following context, answer the question.

Context:
${context}

Question: ${question}

Answer:`;

  // Call your preferred LLM endpoint
  return callLLM(prompt);
}

​
Response Format

​
Success Response (200 OK)

{
  status: "success";
  result: Array<{
    id: string;           // Unique chunk ID
    text: string;         // The text content of the chunk
    similarity: number;   // Similarity score (0-1)
    subsource: string;    // Attachment ID
    subname: string;      // Filename
    url: string | null;   // Source URL if provided during upload
    index: number;        // Result index (0-based)
  }>;
}

​
Example Response

{
  "status": "success",
  "result": [
    {
      "id": "chunk_abc123",
      "text": "Q4 revenue projections indicate a 15% increase compared to Q3, driven primarily by strong enterprise sales in the EMEA region...",
      "similarity": 0.89,
      "subsource": "att_xyz789",
      "subname": "quarterly-report-2024.pdf",
      "url": "https://example.com/reports/q4-2024",
      "index": 0
    },
    {
      "id": "chunk_def456",
      "text": "The projected revenue for the fourth quarter takes into account seasonal trends and the impact of new product launches...",
      "similarity": 0.82,
      "subsource": "att_abc456",
      "subname": "financial-forecast.xlsx",
      "url": null,
      "index": 1
    }
  ]
}

​
Error Handling

try {
  const response = await searchKnowledge(query);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error("Invalid request:", error.response.data.message);
        // Possible causes: missing query parameter
        break;
      case 401:
        console.error("Invalid or missing API key");
        break;
      case 403:
        console.error("API key does not have KNOWLEDGE_FOLDER_API scope");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      case 500:
        console.error("Server error");
        break;
    }
  }
}

​
Best Practices

Write clear, specific queries - The search uses semantic similarity, so natural language questions work well. Be specific about what you’re looking for. Handle empty results - If no relevant documents are found, the result array will be empty. Your application should handle this gracefully. Use similarity scores - The similarity score ranges from 0 to 1. Higher scores indicate better matches. Consider filtering results below a certain threshold for your use case. Cite sources - Use the subname and url fields to provide attribution when displaying results to users.
Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

Authorizations

​
Authorization
string
header
required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json
​
query
string
required

The search query

Example:

"API Documentation"

Response

200

Successfully found search result