Upload File to Knowledge Folder

Upload a new file to a Knowledge base

POST /knowledge/{folderId}

Upload a file to a knowledge folder

cURL

curl --request POST \
  --url https://api.langdock.com/knowledge/{folderId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'url=<string>'

import requests

url = "https://api.langdock.com/knowledge/{folderId}"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "url": "<string>" }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('url', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.langdock.com/knowledge/{folderId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.langdock.com/knowledge/{folderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.langdock.com/knowledge/{folderId}"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.langdock.com/knowledge/{folderId}")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.langdock.com/knowledge/{folderId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"url\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public

The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

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

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.

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 (max 256MB)
url	string	No	Optional source URL to associate with the file

Supported File Types

Knowledge bases support the following document types:

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

Executable files and other potentially dangerous file types are blocked for security reasons.

Examples

Upload a File with cURL

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

Upload a File with 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.langdock.com/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

Upload with Source URL

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.langdock.com/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

Response Format

Success Response (200 OK)

{
  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

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

Error Handling

try {
  const response = await uploadFile(folderId, filePath);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error("Invalid request:", error.response.data.message);
        // Possible causes: missing file, unsupported file type, invalid folder ID
        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 408:
        console.error("Upload request timed out");
        break;
      case 413:
        console.error("File size exceeds 256MB limit");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      case 500:
        console.error("Server error");
        break;
    }
  }
}

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:

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.

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

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

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

Authorizations

Authorization · string · header · required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Path Parameters

folderId · string · required

The ID of the knowledge folder

Body

multipart/form-data

file · file

The file to upload

url · string

The associated URL

Response

200

File uploaded successfully