Retrieve Files from Knowledge Folder

List all files in a Knowledge base or get details for a specific file

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

Before You Start

API key scope: Requires an API key with the KNOWLEDGE_FOLDER_API scope. The Knowledge base must be shared with the API key. See Share Knowledge bases with the API for setup instructions.
Knowledge bases: The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

Base URL

https://api.ajan.io

Request Format

Path Parameters

Parameter	Type	Required	Description
`folderId`	string	Yes	The ID of the Knowledge base

Examples

List Files with cURL

bash

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

List Files with JavaScript

javascript

const axios = require("axios");

async function listFiles(folderId) {
  const response = await axios.get(
    `https://api.ajan.io/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

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

{
  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

{
  "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

curl -X GET "https://api.ajan.io/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

{
  "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

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 base");
        break;
      case 404:
        console.error("Knowledge base not found");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      case 500:
        console.error("Server error");
        break;
    }
  }
}

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
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"