Retrieve Files from Knowledge Folder

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

Using our API via a dedicated deployment? Just replace api.odeus.ai 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

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

Examples

List Files with cURL

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

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

{
  "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.odeus.ai/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;
    }
  }
}

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

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
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"