Knowledge Base API — Upload, Search, Delete

Manage RAG documents: upload files, run semantic search against vector embeddings, delete documents, and trigger URL ingestion for agents.

The Knowledge API gives you full control over the documents that power your agents’ Retrieval-Augmented Generation (RAG) capabilities. You can upload files for embedding, run semantic searches against the vector store, delete documents and their associated embeddings, and trigger URL-based ingestion for an agent’s configured web sources.

Uploaded documents are processed asynchronously — the API returns immediately with a PROCESSING status, and the document transitions to COMPLETED or FAILED as the embedding pipeline runs.

All requests require a valid bearer token in the Authorization header.

---

List documents

GET /api/knowledge

Returns a paginated list of all ingested knowledge documents with their metadata and processing status.

knowledgeBaseId · string

Filter results to documents belonging to a specific knowledge base UUID.

page · number · default: "0"

Zero-based page index for pagination.

size · number · default: "20"

Number of documents per page.

content · object[]

Array of KnowledgeContent objects.

Show KnowledgeContent fields

id · string

UUID of the document. Use this in delete and chunk endpoints.

name · string

Original filename or source URL label.

status · string

Processing state: PROCESSING, COMPLETED, or FAILED.

contentType · string

MIME type of the ingested document, e.g. application/pdf or text/plain.

uri · string

The source URI for URL-ingested documents. null for file uploads.

cURL

curl --request GET \
  --url "http://localhost:8080/api/knowledge?page=0&size=20" \
  --header "Authorization: Bearer {token}"

Example response

{
  "content": [
    {
      "id": "3f7a2c89-1e4d-4b2a-9c5f-abc123def456",
      "name": "company-policy-2025.pdf",
      "status": "COMPLETED",
      "contentType": "application/pdf",
      "uri": null
    },
    {
      "id": "8b4e1d23-5f6a-4c3b-a7d8-def456ghi789",
      "name": "onboarding-guide.txt",
      "status": "PROCESSING",
      "contentType": "text/plain",
      "uri": null
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0
}

---

Upload a document

POST /api/knowledge/upload

Uploads a file for ingestion into the vector store. The file is processed asynchronously — the response returns immediately with status: "PROCESSING".

Supported file types: PDF (.pdf), plain text (.txt).

file · file · required

The file to upload. Must be sent as multipart/form-data with the field name file.

knowledgeBaseId · string

Optional UUID of the knowledge base to assign this document to.

description · string

Optional human-readable description of the document’s content.

documentId · string

UUID of the newly created document record. Use this to check status or delete the document.

status · string

Always "PROCESSING" on successful upload.

message · string

Human-readable confirmation message.

cURL

curl --request POST \
  --url "http://localhost:8080/api/knowledge/upload" \
  --header "Authorization: Bearer {token}" \
  --form "file=@/path/to/company-policy-2025.pdf" \
  --form "description=Q1 2025 company policy document"

Example response

{
  "documentId": "3f7a2c89-1e4d-4b2a-9c5f-abc123def456",
  "message": "Upload processing started",
  "status": "PROCESSING"
}

Raw file bytes are not persisted after ingestion — only the extracted text and vector embeddings are stored. If ingestion fails, you must re-upload the original file; retrying a failed file upload via the retry endpoint is not supported.

---

Semantic search

GET /api/knowledge/search?query=string

Runs a semantic similarity search across all ingested documents using pgvector. Returns the most relevant document chunks ranked by embedding similarity.

query · string · required

The natural language query to search for. The server converts this to an embedding and performs a nearest-neighbor search.

[] · object[]

Array of Document objects from the vector store, sorted by relevance score.

Show Document fields

id · string

Chunk identifier in the vector store.

content · string

The text content of the matching chunk.

metadata · object

Source metadata including document name and page number.

cURL

curl --request GET \
  --url "http://localhost:8080/api/knowledge/search?query=remote+work+policy" \
  --header "Authorization: Bearer {token}"

Example response

[
  {
    "id": "chunk_abc_001",
    "content": "Employees may work remotely up to three days per week with manager approval...",
    "metadata": {
      "source": "company-policy-2025.pdf",
      "page": 12
    }
  }
]

---

Delete a document

DELETE /api/knowledge/{id}

Deletes a document and all of its associated vector embeddings from the system. This is a hard delete — all embedding chunks stored in pgvector are removed in cascade.

id · string · required

UUID of the document to delete, as returned by the list or upload endpoints.

cURL

curl --request DELETE \
  --url "http://localhost:8080/api/knowledge/3f7a2c89-1e4d-4b2a-9c5f-abc123def456" \
  --header "Authorization: Bearer {token}"

Returns 204 No Content with an empty body on success.

Deletion is irreversible. All vector embeddings for the document are permanently removed. You must re-upload and re-ingest the document to restore it.

---

Trigger URL ingestion for an agent

POST /api/agents/{agentId}/knowledge/load

Triggers an asynchronous job to scrape and ingest the web URLs configured for the specified agent. Use this to refresh an agent’s knowledge base after its source URLs are updated. Returns a jobId immediately.

agentId · string · required

The unique identifier of the agent whose configured URLs should be ingested.

jobId · string

The identifier of the background ingestion job. You can track progress by monitoring document statuses via GET /api/knowledge.

cURL

curl --request POST \
  --url "http://localhost:8080/api/agents/procurator_assistant/knowledge/load" \
  --header "Authorization: Bearer {token}"

Example response

{
  "jobId": "job_9d2e4c78-3a1b-4f5e-8d6c-xyz789abc012"
}

Document status transitions (PROCESSING → COMPLETED or FAILED) can be monitored by polling GET /api/knowledge and checking the status field of the document.