Knowledge base

Upload documents to give your agent grounded, retrievable facts.

How it works

When you upload a document, Aethex splits it into chunks, embeds each chunk, and stores the vectors in pgvector alongside a pg_trgm keyword index. At call time, retrieval fuses vector and keyword results (RRF), drops chunks below the relevance floor, and injects the best remaining chunks into the prompt as context.

If the content is already on the web

You do not have to export a page to a file first. Attach its URL as a reference link and Aethex crawls it into this same knowledge base, then re-reads it on a schedule so it does not go stale. The documents it produces are the ones described below. The difference is how they get here, and that a crawled page waits for your approval before it is served.

Supported formats

.pdfPDF

Parsed including headers and tables. Scanned-only PDFs without embedded text are not supported.

.docxDOCX

Word documents. Inline images are skipped; text content and tables are indexed.

.txt / .mdPlain text

UTF-8 text files and Markdown. Markdown structure (headings, lists) is preserved during chunking.

Upload a document

POST the file to the agent's knowledge-base endpoint. Processing is asynchronous; the document enters a `processing` state and is available for retrieval once status becomes `ready`.

upload_doc.py

python

import os, requests

API_KEY = os.environ["AETHEX_API_KEY"]
BASE_URL = "https://api.aethexai.com/api/v1"
AGENT_ID = "ag_..."

with open("support_runbook.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE_URL}/agents/{AGENT_ID}/knowledge-base",
        headers={"X-API-Key": API_KEY},
        files={"file": ("support_runbook.pdf", f, "application/pdf")},
    )
resp.raise_for_status()
print(resp.json())

Note

Uploads are routed through a presigned URL for files above ~10 MB. Use POST /uploads/presign with kind: "doc/knowledge-base" to get the URL, PUT the file directly to that URL, then call POST /agents/{id}/knowledge-base with the returned upload_id instead of the file.

Best practices

Chunk size matters. Shorter, focused documents retrieve better than one giant file. If you have a 200-page manual, split it into logical sections.
Keep text machine-readable. Scanned images without OCR text won't index. Export PDFs with embedded text, or use DOCX/TXT instead.
Name your documents. The filename appears in retrieval metadata and helps with debugging. Use descriptive names like `returns_policy_2025.pdf` rather than `doc1.pdf`.
Update, don't accumulate. Delete outdated documents rather than uploading new versions alongside them. Stale documents lower retrieval precision.

Document lifecycle

Reprocess

POST/agents/{id}/knowledge-base/{doc_id}/process

Re-chunk and re-embed an existing document. Useful after the embedding model is updated or if indexing failed.

Delete

DELETE/agents/{id}/knowledge-base/{doc_id}

Removes the document and all its vector chunks immediately. The agent loses access to that content on the next call.