Knowledge Folder'dan dosyaları getir

Bir Knowledge base'deki tüm dosyaları listeleyin veya belirli bir dosyanın ayrıntılarını alın

Belirtilen bir Knowledge base'deki tüm dosyaları (attachment'ları) listeler. Hangi dosyaların mevcut olduğunu görmek ve işleme durumlarını kontrol etmek için bu endpoint'i kullanın.

Başlamadan önce

API key scope: KNOWLEDGE_FOLDER_API kapsamına sahip bir API anahtarı gerekir. Knowledge base API anahtarıyla paylaşılmış olmalıdır. Kurulum için Share Knowledge bases with the API sayfasına bakın.
Knowledge bases: Knowledge Folder API, Library'de Knowledge base olarak görünen kaynakları yönetir.

Base URL

https://api.ajan.io

Dedicated deployments Tüm isteklerde api.ajan.com'u /api/public ile değiştirin.

Request Format

Path Parameters

Parameter	Type	Required	Description
`folderId`	string	Yes	Knowledge base ID'si

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`	Dosya yükleniyor
`UPLOADED`	Dosya yüklendi ve işleme kuyruğunda
`EXTRACTING`	Dosyadan metin çıkarılıyor
`EMBEDDING`	Embedding'ler üretiliyor
`SYNCED`	Dosya arama için hazır
`ACTION_FAILED`	İşleme eylemi başarısız
`EXTRACTION_FAILED`	Metin çıkarma başarısız
`EMBEDDING_FAILED`	Embedding üretimi başarısız
`TIMEOUT`	İşleme zaman aşımına uğradı

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

Belirli bir dosyanın ayrıntıları için GET /knowledge/{folderId}/{attachmentId} endpoint'ini kullanın:

bash

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

Bu, tek bir attachment için yukarıdaki alanların aynısını döndürür; işleme başarısız olduysa bir hata mesajı da ekler:

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;
    }
  }
}

ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.

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"