> ## 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.

# Retrieve Files from Knowledge Folder

> List all files in a knowledge folder or get details for a specific file

<Info>
  **Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

Lists all files (attachments) in a specified knowledge folder. Use this endpoint to see what files are available and check their processing status.

<Info>
  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](/en/developer/knowledge-folder-api/sharing) for setup instructions.
</Info>

## Request Format

### Path Parameters

| Parameter  | Type   | Required | Description                    |
| ---------- | ------ | -------- | ------------------------------ |
| `folderId` | string | Yes      | The ID of the knowledge folder |

## Examples

### List Files with cURL

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

### List Files with JavaScript

```javascript theme={null}
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

```javascript theme={null}
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)

```typescript theme={null}
{
  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

| Status              | Description                                |
| ------------------- | ------------------------------------------ |
| `UPLOADING`         | File is being uploaded                     |
| `UPLOADED`          | File is uploaded and queued for processing |
| `EXTRACTING`        | Text is being extracted from the file      |
| `EMBEDDING`         | Embeddings are being generated             |
| `SYNCED`            | File is ready for search                   |
| `ACTION_FAILED`     | Processing action failed                   |
| `EXTRACTION_FAILED` | Text extraction failed                     |
| `EMBEDDING_FAILED`  | Embedding generation failed                |
| `TIMEOUT`           | Processing timed out                       |

### Example Response

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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

```typescript theme={null}
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;
    }
  }
}
```

<Info>
  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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml get /knowledge/{folderId}/list
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
security:
  - bearerAuth: []
paths:
  /knowledge/{folderId}/list:
    get:
      summary: Retrieve files from a knowledge folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: The ID of the knowledge folder
          schema:
            type: string
      responses:
        '200':
          description: List of files retrieved successfully
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````