Upload Document

Endpoint

POST /apiops/projects/{projectName}/knowledge-bases/{kbName}/documents/

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	multipart/form-data	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
kbName	string	Yes	Knowledge base name (parent, resolved by name)

Query Parameters

None

Form Data

Parameter	Type	Required	Description
file	file	Yes	The document file to upload (multipart file part)

Notes

• file must not be empty.
• The parent knowledge base is resolved by kbName; the uploaded document is scoped to that knowledge base and the resolved project.
• The service computes a SHA-256 content hash and deduplicates by it, so re-uploading identical content does not create duplicate chunks.

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "resultList": [
    {
      "id": "6651b3c4e4b0c3a2d1f0aaaa",
      "knowledgeBaseId": "6650a1f2e4b0c3a2d1f09876",
      "projectId": "6650a1f2e4b0c3a2d1f01234",
      "fileName": "user-guide.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 248193,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "status": "PENDING",
      "chunkCount": 0,
      "uploadedAt": "2026-07-11T10:05:00Z",
      "errorMessage": null
    }
  ],
  "resultCount": 1
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE
resultList	array	Single-element list containing the uploaded document object
resultCount	integer	Number of documents returned (1)

Document Object Fields

Field	Type	Description
id	string	Server-generated document identifier (used to address the document)
knowledgeBaseId	string	Internal id of the parent knowledge base
projectId	string	Internal id of the owning project
fileName	string	Original uploaded file name
contentType	string	MIME type detected on upload
sizeBytes	integer	File size in bytes
sha256	string	SHA-256 content hash (used for deduplication)
status	string	Processing status: PENDING, CHUNKED, INDEXED, ERROR
chunkCount	integer	Number of indexed chunks (read-only; 0 until indexed)
uploadedAt	string	ISO-8601 upload timestamp
errorMessage	string	Error detail when status is ERROR; null otherwise

Document Status Values

• PENDING - Uploaded, not yet processed
• CHUNKED - Text split into chunks; embedding generation in progress
• INDEXED - Chunks embedded and upserted to the VectorDB; queryable
• ERROR - Processing failed at some stage; see errorMessage

EnumStatus

• SUCCESS - Operation successful
• FAILURE - Operation failed

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "File can not be empty!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Knowledge base (name: product-docs) was not found!"
}

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/knowledge-bases/product-docs/documents/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@user-guide.pdf"

Notes and Warnings

• Multipart Only: The request must be multipart/form-data with a file part. An empty file returns 400 Bad Request.
• Asynchronous Indexing: The returned document has status PENDING. Chunking and embedding run in the background; poll Get Document or List Documents until status becomes INDEXED.
• Deduplication: Documents are deduplicated by SHA-256 content hash within the knowledge base.
• Documents Are Addressed By Id: The response id is how you subsequently get or delete the document. Filenames are not unique within a knowledge base, so documents are a deliberate id-based exception to the otherwise name-based APIops model.
• Internal Storage Reference Hidden: The document's internal storage reference (gridFsFileId) is intentionally excluded from responses.
• Permissions: Requires AI_DEVELOPMENT + MANAGE permission in the project.

Related Documentation

• List Documents - List documents in the knowledge base
• Get Document - Get a single document by id
• Delete Document - Remove a document and its vectors
• Knowledge Bases API - Resource overview