Skip to main content
GET
/
knowledge
/
{folderId}
/
list
Retrieve files from a knowledge folder
curl --request GET \
  --url https://api.langdock.com/knowledge/{folderId}/list \
  --header 'Authorization: Bearer <token>'

Documentation Index

Fetch the complete documentation index at: https://docs.langdock.com/llms.txt

Use this file to discover all available pages before exploring further.

Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public
Lists all files (attachments) in a specified knowledge folder. Use this endpoint to see what files are available and check their processing status.
Requires an API key with the KNOWLEDGE_FOLDER_API scope. The knowledge folder must be shared with the API key. See Share Knowledge Folders with the API for setup instructions.

​
Request Format

​
Path Parameters

ParameterTypeRequiredDescription
folderIdstringYesThe ID of the knowledge folder

​
Examples

​
List Files with cURL

curl -X GET "https://api.langdock.com/knowledge/{folderId}/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
List Files with JavaScript

const axios = require("axios");

async function listFiles(folderId) {
  const response = await axios.get(
    `https://api.langdock.com/knowledge/${folderId}/list`,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  return response.data;
}

// Example usage
const files = await listFiles("folder_abc123");
console.log(`Found ${files.result.length} files`);

files.result.forEach((file) => {
  console.log(`- ${file.name} (${file.syncStatus})`);
});

​
Check Processing Status

async function waitForProcessing(folderId, attachmentId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const files = await listFiles(folderId);
    const file = files.result.find((f) => f.id === attachmentId);

    if (!file) {
      throw new Error("File not found");
    }

    if (file.syncStatus === "SYNCED") {
      console.log("File processing complete!");
      return file;
    }

    if (
      file.syncStatus === "ACTION_FAILED" ||
      file.syncStatus === "EXTRACTION_FAILED" ||
      file.syncStatus === "EMBEDDING_FAILED" ||
      file.syncStatus === "TIMEOUT"
    ) {
      throw new Error(`Processing failed: ${file.syncStatus}`);
    }

    console.log(`Processing... (${file.syncStatus})`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  throw new Error("Processing timeout");
}

​
Response Format

​
Success Response (200 OK)

{
  status: "success";
  result: Array<{
    id: string;              // Unique attachment ID
    name: string;            // Original filename
    mimeType: string;        // MIME type of the file
    createdAt: string;       // ISO 8601 timestamp
    updatedAt: string;       // ISO 8601 timestamp
    url: string | null;      // Source URL if provided during upload
    path: string | null;     // Storage path
    syncStatus: string;      // Processing status (see below)
    pageCount: number | null; // Number of pages (for PDFs)
    summary: string | null;  // Auto-generated summary
    externalId: string | null; // External reference ID
    syncParams: object | null; // Sync configuration from the source integration
  }>;
}

​
Processing Status Values

StatusDescription
UPLOADINGFile is being uploaded
UPLOADEDFile is uploaded and queued for processing
EXTRACTINGText is being extracted from the file
EMBEDDINGEmbeddings are being generated
SYNCEDFile is ready for search
ACTION_FAILEDProcessing action failed
EXTRACTION_FAILEDText extraction failed
EMBEDDING_FAILEDEmbedding generation failed
TIMEOUTProcessing timed out

​
Example Response

{
  "status": "success",
  "result": [
    {
      "id": "att_abc123def456",
      "name": "quarterly-report.pdf",
      "mimeType": "application/pdf",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z",
      "url": "https://example.com/reports/q4",
      "path": "/attachments/abc123/quarterly-report.pdf",
      "syncStatus": "SYNCED",
      "pageCount": 15,
      "summary": "This quarterly report covers Q4 2024 financial performance...",
      "externalId": null,
      "syncParams": null
    },
    {
      "id": "att_xyz789ghi012",
      "name": "product-specs.docx",
      "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "createdAt": "2025-01-14T08:00:00.000Z",
      "updatedAt": "2025-01-14T08:05:00.000Z",
      "url": null,
      "path": "/attachments/xyz789/product-specs.docx",
      "syncStatus": "SYNCED",
      "pageCount": null,
      "summary": "Product specifications document covering technical requirements...",
      "externalId": null,
      "syncParams": null
    },
    {
      "id": "att_new456abc",
      "name": "meeting-notes.txt",
      "mimeType": "text/plain",
      "createdAt": "2025-01-16T14:00:00.000Z",
      "updatedAt": "2025-01-16T14:00:00.000Z",
      "url": null,
      "path": "/attachments/new456/meeting-notes.txt",
      "syncStatus": "EXTRACTING",
      "pageCount": null,
      "summary": null,
      "externalId": null,
      "syncParams": null
    }
  ]
}

​
Get Single File Details

To get details for a specific file, use the GET /knowledge/{folderId}/{attachmentId} endpoint: 
curl -X GET "https://api.langdock.com/knowledge/{folderId}/{attachmentId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
This returns the same fields as above for a single attachment, plus an error message if processing failed: 
{
  "status": "error",
  "message": "File processing failed. Please try uploading again or contact support.",
  "result": {
    "id": "att_failed123",
    "name": "corrupted-file.pdf",
    "syncStatus": "EXTRACTION_FAILED",
    "syncMessage": "Unable to extract text from PDF"
  }
}

​
Error Handling

try {
  const response = await listFiles(folderId);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error("Invalid request:", error.response.data.message);
        break;
      case 401:
        console.error("Invalid or missing API key");
        break;
      case 403:
        console.error("API key does not have access to this knowledge folder");
        break;
      case 404:
        console.error("Knowledge folder not found");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      case 500:
        console.error("Server error");
        break;
    }
  }
}
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"

Path Parameters

​
folderId
string
required

The ID of the knowledge folder

Response

200

List of files retrieved successfully