Knowledge Folder'a dosya yükle

Bir Knowledge base'e yeni bir dosya yükleyin

Belirtilen bir Knowledge base'e yeni bir dosya yükler. Dosya işlenir, embedding'lenir ve anlamsal arama için kullanılabilir hale gelir.

Başlamadan önce

API key scope: KNOWLEDGE_FOLDER_API kapsamına sahip bir API anahtarı gerekir. API anahtarının kendisinin Knowledge base üzerinde Editor rolü 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

Bu endpoint, dosyanın eklendiği multipart/form-data isteklerini kabul eder.

Path Parameters

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

Form Fields

Field	Type	Required	Description
`file`	file	Yes	Yüklenecek dosya. Aşağıdaki boyut limitlerine bakın.
`url`	string	No	Dosyayla ilişkilendirilecek isteğe bağlı kaynak URL

Dosya boyutu limitleri türe göre değişir: düz metin, Markdown, JSON ve VTT için 10 MB; XML için 30 MB; diğer desteklenen belge türleri için 256 MB. Desteklenen biçimler için supported file types reference sayfasına bakın.

Supported File Types

Knowledge base'ler şu belge ve metin biçimlerini destekler:

PDF (.pdf)
Word belgeleri (.doc, .docx)
Metin dosyaları (.txt)
Markdown (.md)
HTML (.html)
PowerPoint (.pptx, .ppt)

Ek biçimler için supported file types reference sayfasına bakın. Bu endpoint elektronik tablo, görüntü, ses ve video dosyalarını reddeder.

Çalıştırılabilir dosyalar ve diğer potansiyel olarak tehlikeli dosya türleri güvenlik nedeniyle engellenir.

Examples

Upload a File with cURL

bash

curl -X POST "https://api.ajan.io/knowledge/{folderId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"

Upload a File with JavaScript

javascript

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

async function uploadFile(folderId, filePath) {
  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));

  const response = await axios.post(
    `https://api.ajan.io/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

Upload with Source URL

javascript

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

async function uploadFileWithUrl(folderId, filePath, sourceUrl) {
  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));
  form.append("url", sourceUrl);

  const response = await axios.post(
    `https://api.ajan.io/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

Response Format

Success Response (200 OK)

typescript

{
  status: "success";
  result: {
    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
  };
}

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:30:00.000Z",
    "url": null
  }
}

File Validation Response (400 Bad Request)

Dosya doğrulamadan geçmezse API, nedeni message alanında döndürür:

json

{
  "message": "The file \"quarterly-report.pdf\" is declared as a PDF but its content does not start with the expected PDF header.",
  "code": "BAD_REQUEST"
}

Error Handling

javascript

try {
  const response = await uploadFile(folderId, filePath);
} catch (error) {
  if (error.response) {
    console.error(error.response.data.message ?? "Upload failed");
  }
}

Status	Meaning
`400`	Geçersiz istek veya dosya doğrulama hatası
`401`	Geçersiz veya eksik API anahtarı
`403`	API anahtarının Knowledge base'e erişimi yok
`404`	Knowledge base bulunamadı
`408`	Yükleme zaman aşımına uğradı
`413`	Dosya boyut limitini aşıyor
`429`	Rate limit aşıldı
`500`	Beklenmeyen sunucu hatası
`503`	Depolama kapasitesi aşıldı

Processing Status

Yüklemeden sonra dosya asenkron işlenir. İşleme durumunu kontrol etmek için Retrieve Files endpoint'ini kullanın. syncStatus alanı mevcut durumu gösterir:

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, EXTRACTION_FAILED, EMBEDDING_FAILED, TIMEOUT — İşleme başarısız

Async Upload Variant

Büyük dosyalar için veya yükleme yanıtını beklemeniz gerekmediğinde async upload endpoint'ini kullanabilirsiniz:

text

POST /knowledge/{folderId}/upload-async

Bu endpoint aynı multipart/form-data alanlarını kabul eder ve dosya alındıktan sonra 202 Accepted döndürür. İşleme arka planda devam eder.

json

{
  "status": "processing",
  "result": {
    "id": "att_abc123def456",
    "name": "quarterly-report.pdf",
    "mimeType": "application/pdf",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "url": null,
    "processingStatus": "UPLOADED",
    "statusUrl": "/api/public/knowledge/{folderId}/{attachmentId}"
  },
  "message": "File uploaded successfully and is being processed in the background. Poll the statusUrl to check when processing completes (syncStatus: SYNCED)."
}

Dosya doğrulaması, API yüklemeyi kabul etmeden önce yapılır. Doğrulama başarısız olursa async endpoint, 202 Accepted yerine yukarıdaki 400 Bad Request yanıtını döndürür.

İşleme durumunu yoklamak için GET {statusUrl} kullanın. Yanıt, result.syncStatus içinde mevcut durumu döndürür.

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}:
    post:
      summary: Upload a file to a knowledge folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: The ID of the knowledge folder
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                url:
                  type: string
                  description: The associated URL
      responses:
        '200':
          description: File uploaded successfully
        '400':
          description: Invalid request or file validation failed
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    additionalProperties: false
                    required:
                      - message
                      - code
                    properties:
                      message:
                        type: string
                        example: >-
                          The file "quarterly-report.pdf" is declared as a PDF
                          but its content does not start with the expected PDF
                          header.
                      code:
                        type: string
                        enum:
                          - BAD_REQUEST
                  - type: object
                    additionalProperties: false
                    required:
                      - message
                      - errors
                    properties:
                      message:
                        type: string
                        example: Invalid request
                      errors:
                        type: array
                        items:
                          type: object
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: The provided API key is invalid.
        '403':
          description: API key does not have access to the knowledge folder
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    additionalProperties: false
                    required:
                      - message
                      - code
                    properties:
                      message:
                        type: string
                        example: >-
                          Knowledge folder not shared with this API key. Please
                          share the folder with the API key in the ajan App
                          to upload or update files.
                      code:
                        type: string
                        enum:
                          - FORBIDDEN
                  - type: object
                    additionalProperties: false
                    required:
                      - message
                      - error
                      - details
                    properties:
                      message:
                        type: string
                        example: Insufficient API key permissions.
                      error:
                        type: string
                        enum:
                          - INSUFFICIENT_SCOPES
                      details:
                        type: object
                        required:
                          - required
                          - missing
                        properties:
                          required:
                            type: array
                            items:
                              type: string
                              example: KNOWLEDGE_FOLDER_API
                          missing:
                            type: array
                            items:
                              type: string
                              example: KNOWLEDGE_FOLDER_API
                  - type: object
                    additionalProperties: false
                    required:
                      - message
                    properties:
                      message:
                        type: string
                        example: Forbidden
        '404':
          description: Knowledge folder not found
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - code
                properties:
                  message:
                    type: string
                    example: Knowledge folder not found
                  code:
                    type: string
                    enum:
                      - NOT_FOUND
        '408':
          description: Upload timed out
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - code
                properties:
                  message:
                    type: string
                    example: >-
                      Upload request timed out. Please try again with a smaller
                      file or check your connection.
                  code:
                    type: string
                    enum:
                      - REQUEST_TIMEOUT
        '413':
          description: File exceeds the size limit
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - code
                properties:
                  message:
                    type: string
                    example: >-
                      File size exceeds the maximum allowed size of 256MB.
                      Please upload a smaller file.
                  code:
                    type: string
                    enum:
                      - PAYLOAD_TOO_LARGE
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: >-
                      You have exceeded the maximum number of requests per
                      minute (50)
                  code:
                    type: string
                    enum:
                      - TOO_MANY_REQUESTS
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: Internal server error
        '503':
          description: Storage capacity exceeded
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - code
                properties:
                  message:
                    type: string
                    example: >-
                      Storage capacity exceeded. Please contact your
                      administrator.
                  code:
                    type: string
                    enum:
                      - SERVICE_UNAVAILABLE
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"