Upload Knowledge Base Document

POST

documents

upload

curl --request POST \
  --url https://api.dialnexa.com/v1/documents/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'title=Support FAQ' \
  --form knowledge_base_id=kb_abc123def45678

import requests

url = "https://api.dialnexa.com/v1/documents/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Support FAQ",
    "knowledge_base_id": "kb_abc123def45678"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('file', 'support-faq.txt');
form.append('title', 'Support FAQ');
form.append('knowledge_base_id', 'kb_abc123def45678');

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

options.body = form;

fetch('https://api.dialnexa.com/v1/documents/upload', 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.dialnexa.com/v1/documents/upload",
  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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\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.dialnexa.com/v1/documents/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\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.dialnexa.com/v1/documents/upload")
  .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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/documents/upload")

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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\r\n-----011000010111000001101001--"

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

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "abc123def45678",
    "title": "Support FAQ",
    "knowledge_base_id": "abc123def45678",
    "document_type": "txt",
    "file_size": 1,
    "is_deleted": false
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "Missing fields, unsupported file, or document count limit reached.",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "Missing or invalid API key.",
  "error": "Unauthorized"
}

{
  "statusCode": 404,
  "message": "Knowledge base not found in this workspace.",
  "error": "Not Found"
}

{
  "statusCode": 409,
  "message": "A document with this title already exists.",
  "error": "Conflict"
}

{
  "statusCode": 413,
  "message": "File exceeds the 100 MB upload limit.",
  "error": "Payload Too Large"
}

{
  "statusCode": 500,
  "message": "Document parsing, storage, or indexing failed.",
  "error": "Internal Server Error"
}

Changes state - verify before retry Upload a knowledge base document to store and index a PDF or TXT file for agent retrieval. The knowledge base must already exist in the authenticated workspace.

Before you begin

Create a knowledge base and keep its kb_ ID.
Prepare a PDF or TXT file no larger than 100 MB (104857600 bytes).
Choose a non-empty title unique within that knowledge base. Each knowledge base allows 25 non-deleted documents.

Upload Knowledge Base Document Request

curl https://api.dialnexa.com/v1/documents/upload \
  -H "Authorization: Bearer $DIALNEXA_API_KEY" \
  -F "knowledge_base_id=kb_abc123" \
  -F "title=Support FAQ" \
  -F "[email protected];type=text/plain"

Optional description and source fields describe the file. Let your HTTP client set the multipart boundary.

Verify the result

A 201 response contains the created document in data, including its ID, title, knowledge base ID, file type, and size. List Knowledge Base Documents and confirm the file is present. Attach the knowledge base to the intended agent and ask a test question covered by the document.

Errors and recovery

Status	Recovery
`400`	Check required fields, PDF/TXT format, and the 25-document limit.
`401`	Correct the API key.
`404`	Select a knowledge base in this workspace.
`409`	A document with the same title exists. Inspect it before choosing another title.
`413`	Reduce the file below the 100 MB limit.
`500`	Parsing, storage, or indexing failed. Inspect the document list before retrying.

Uploading stores a file and indexes its content. It is not an idempotent replacement operation. After an uncertain response, list documents before retrying; changing the title can create duplicate content. To replace an existing document, use dashboard document management.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

file

required

PDF or TXT file, at most 100 MB (104857600 bytes).

title

string

required

Minimum string length: 1

knowledge_base_id

string

required

description

string

source

string

Response

Successful response.

success

boolean

required

error

boolean

required

statusCode

integer

required

message

string

required

data

object

required

Show child attributes

timestamp

string<date-time>

required

Upload Knowledge Base Document

curl --request POST \
  --url https://api.dialnexa.com/v1/documents/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'title=Support FAQ' \
  --form knowledge_base_id=kb_abc123def45678

import requests

url = "https://api.dialnexa.com/v1/documents/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Support FAQ",
    "knowledge_base_id": "kb_abc123def45678"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('file', 'support-faq.txt');
form.append('title', 'Support FAQ');
form.append('knowledge_base_id', 'kb_abc123def45678');

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

options.body = form;

fetch('https://api.dialnexa.com/v1/documents/upload', 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.dialnexa.com/v1/documents/upload",
  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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\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.dialnexa.com/v1/documents/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\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.dialnexa.com/v1/documents/upload")
  .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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/documents/upload")

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\nsupport-faq.txt\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nSupport FAQ\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"knowledge_base_id\"\r\n\r\nkb_abc123def45678\r\n-----011000010111000001101001--"

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

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "abc123def45678",
    "title": "Support FAQ",
    "knowledge_base_id": "abc123def45678",
    "document_type": "txt",
    "file_size": 1,
    "is_deleted": false
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

{
  "statusCode": 400,
  "message": "Missing fields, unsupported file, or document count limit reached.",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "Missing or invalid API key.",
  "error": "Unauthorized"
}

{
  "statusCode": 404,
  "message": "Knowledge base not found in this workspace.",
  "error": "Not Found"
}

{
  "statusCode": 409,
  "message": "A document with this title already exists.",
  "error": "Conflict"
}

{
  "statusCode": 413,
  "message": "File exceeds the 100 MB upload limit.",
  "error": "Payload Too Large"
}

{
  "statusCode": 500,
  "message": "Document parsing, storage, or indexing failed.",
  "error": "Internal Server Error"
}

Overview

Endpoints

Before you begin

Upload Knowledge Base Document Request

Verify the result

Errors and recovery

Authorizations

Body

Response

​Before you begin

​Upload Knowledge Base Document Request

​Verify the result

​Errors and recovery

​Related endpoints

Authorizations

Body

Response

Before you begin

Upload Knowledge Base Document Request

Verify the result

Errors and recovery

Related endpoints