Documents

Upload documents to give a character knowledge. Uploaded files are automatically chunked, embedded, and indexed — when the character responds, relevant chunks are retrieved and included as context (RAG).

The Document object

{
  "id": "doc_AbCdEfGh12345678",
  "createdAt": "2026-01-15T12:00:00Z",
  "characterId": "character_PuTlWmWuynYZu8sP",
  "name": "world-lore.pdf",
  "mimeType": "application/pdf",
  "fileSize": 524288,
  "status": "ready",
  "chunkCount": 42,
  "errorMessage": null
}

Field	Type	Description
id	string	Unique identifier (doc_ prefix)
characterId	string	Character this document belongs to
name	string	Original file name
mimeType	string	File MIME type
fileSize	number	Size in bytes
status	string	Processing status (see below)
chunkCount	number	Number of indexed chunks
errorMessage	string | null	Error details if processing failed

Document status

Status	Description
pending	Uploaded, waiting to be processed
processing	Currently being chunked and embedded
ready	Processed and available for retrieval
failed	Processing failed (check errorMessage)

Upload a document

POST /characters/{characterId}/documents

Upload a file as multipart/form-data. Processing happens asynchronously — the response returns immediately with status pending.

Supported file types

Type	MIME type
PDF	application/pdf
Word (.docx)	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Plain text	text/plain
Markdown	text/markdown
HTML	text/html
Images	image/png, image/jpeg, image/webp

Maximum file size: 50 MB.

curl

curl -X POST https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP/documents \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -F "file=@world-lore.pdf"

Returns a Document object with status 202 Accepted.

List documents

GET /characters/{characterId}/documents

curl https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP/documents \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"

Get a document

GET /characters/{characterId}/documents/{documentId}

Delete a document

DELETE /characters/{characterId}/documents/{documentId}

Deletes the document and removes all associated chunks from the vector index.

{ "id": "doc_AbCdEfGh12345678", "deleted": true }

Reprocess a document

POST /characters/{characterId}/documents/{documentId}/reprocess

Re-queues the document for processing. Useful if processing previously failed or if the chunking pipeline has been updated.

curl -X POST https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP/documents/doc_AbCdEfGh12345678/reprocess \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"

Returns the document with status reset to pending.