Skip to main content

Documentation Index

Fetch the complete documentation index at: https://operativusai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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.
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 --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.
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.
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 --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 --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.