> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<ParamField query="knowledgeBaseId" type="string">
  Filter results to documents belonging to a specific knowledge base UUID.
</ParamField>

<ParamField query="page" type="number" default="0">
  Zero-based page index for pagination.
</ParamField>

<ParamField query="size" type="number" default="20">
  Number of documents per page.
</ParamField>

<ResponseField name="content" type="object[]">
  Array of `KnowledgeContent` objects.

  <Expandable title="KnowledgeContent fields">
    <ResponseField name="id" type="string">
      UUID of the document. Use this in delete and chunk endpoints.
    </ResponseField>

    <ResponseField name="name" type="string">
      Original filename or source URL label.
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing state: `PROCESSING`, `COMPLETED`, or `FAILED`.
    </ResponseField>

    <ResponseField name="contentType" type="string">
      MIME type of the ingested document, e.g. `application/pdf` or `text/plain`.
    </ResponseField>

    <ResponseField name="uri" type="string">
      The source URI for URL-ingested documents. `null` for file uploads.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/knowledge?page=0&size=20" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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`).

<ParamField body="file" type="file" required>
  The file to upload. Must be sent as `multipart/form-data` with the field name `file`.
</ParamField>

<ParamField body="knowledgeBaseId" type="string">
  Optional UUID of the knowledge base to assign this document to.
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable description of the document's content.
</ParamField>

<ResponseField name="documentId" type="string">
  UUID of the newly created document record. Use this to check status or delete the document.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"PROCESSING"` on successful upload.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation message.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Example response**

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

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

***

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

<ParamField query="query" type="string" required>
  The natural language query to search for. The server converts this to an embedding and performs a nearest-neighbor search.
</ParamField>

<ResponseField name="[]" type="object[]">
  Array of `Document` objects from the vector store, sorted by relevance score.

  <Expandable title="Document fields">
    <ResponseField name="id" type="string">
      Chunk identifier in the vector store.
    </ResponseField>

    <ResponseField name="content" type="string">
      The text content of the matching chunk.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Source metadata including document name and page number.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/knowledge/search?query=remote+work+policy" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
[
  {
    "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.

<ParamField path="id" type="string" required>
  UUID of the document to delete, as returned by the list or upload endpoints.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/knowledge/3f7a2c89-1e4d-4b2a-9c5f-abc123def456" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

Returns `204 No Content` with an empty body on success.

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

***

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

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent whose configured URLs should be ingested.
</ParamField>

<ResponseField name="jobId" type="string">
  The identifier of the background ingestion job. You can track progress by monitoring document statuses via `GET /api/knowledge`.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/agents/procurator_assistant/knowledge/load" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "jobId": "job_9d2e4c78-3a1b-4f5e-8d6c-xyz789abc012"
}
```

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