Upload File to Knowledge Folder

Upload a new file to a Knowledge base

Uploads a new file to a specified Knowledge base. The file will be processed, embedded, and made available for semantic search.

Before You Start

API key scope: Requires an API key with the KNOWLEDGE_FOLDER_API scope. The API key itself needs the Editor role on the Knowledge base. 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

This endpoint accepts multipart/form-data requests with the file attached.

Path Parameters

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

Form Fields

Field	Type	Required	Description
`file`	file	Yes	The file to upload. See size limits below.
`url`	string	No	Optional source URL to associate with the file

File size limits depend on the file type: 10 MB for plain text, Markdown, JSON, and VTT files; 30 MB for XML files; and 256 MB for other supported document types. See the supported file types reference for supported formats.

Supported File Types

Knowledge bases support document and text formats such as:

PDF (.pdf)
Word documents (.doc, .docx)
Text files (.txt)
Markdown (.md)
HTML (.html)
PowerPoint (.pptx, .ppt)

See the supported file types reference for additional formats. This endpoint rejects spreadsheet, image, audio, and video files.

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)

If the file fails validation, the API returns the reason in message:

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`	Invalid request or file validation failure
`401`	Invalid or missing API key
`403`	API key does not have access to the Knowledge base
`404`	Knowledge base not found
`408`	Upload timed out
`413`	File exceeds the size limit
`429`	Rate limit exceeded
`500`	Unexpected server error
`503`	Storage capacity exceeded

Processing Status

After upload, the file is processed asynchronously. Use the Retrieve Files endpoint to check processing status. The syncStatus field indicates the current state:

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, EXTRACTION_FAILED, EMBEDDING_FAILED, TIMEOUT - Processing failed

Async Upload Variant

For large files or when you don't need to wait for the upload response, you can use the async upload endpoint:

text

POST /knowledge/{folderId}/upload-async

This endpoint accepts the same multipart/form-data fields and returns 202 Accepted after the file is received. Processing continues in the background.

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)."
}

File validation happens before the API accepts the upload. If validation fails, the async endpoint returns the same 400 Bad Request response shown above instead of 202 Accepted.

Use GET {statusUrl} to poll processing status. The response returns the current status in result.syncStatus.

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"