Knowledge

The knowledge base holds the documents you add to LVNG. Upload a file and LVNG reads its text, splits it into passages and stores them, so you and Tron can search them later. Every document belongs to your organization, one workspace, or only you.

Base path: /api/knowledge|Auth: session token or API key (except health)|Rate limit: 30 requests/min

File types: PDF, Word (.docx), text, Markdown, JSON, YAML, XML, HTML and source code files, up to 50 MB each. Any other type is refused with 415 and the list of supported extensions.

API key scopes: uploading needs write or knowledge:write; searching and reading a document need read or knowledge:read. A key made for one workspace adds documents only to that workspace or to your own documents.

Health Check

GET/api/knowledge/health

Says the knowledge service is up and lists the file extensions it reads. Does not require authentication.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "ok",
  "service": "knowledge-api",
  "version": "1.0.0",
  "supportedFormats": [".pdf", ".docx", ".txt", ".md", ".json", ".yaml", ".html"],
  "timestamp": "2026-10-13T10:00:00.000Z"
}

Upload a Document

POST/api/knowledge/uploadAuthenticated

Uploads one file as multipart/form-data (field name file). LVNG reads its text, splits it into passages and stores the document with its original. Answers 201 with the new document's id. A JSON body is refused with 400 'No file uploaded'.

Body Parameters

filefilerequired

The document to add.

scopestring

Default: "organization"

Who can read it: organization, workspace or personal.

workspaceIdstring (UUID)

The workspace to add it to. Required when scope is workspace; you must be an owner, admin or member there.

categorystring

Default: "general"

A category to file it under.

tagsstring (JSON array)

Default: "[]"

Tags as a JSON array, for example ["hr","handbook"].

chunkSizenumber

Default: 1000

Characters per passage.

chunkOverlapnumber

Default: 200

Characters shared by neighbouring passages.

Request

cURL

curl -X POST https://api.lvng.ai/api/knowledge/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@remote-work-policy.pdf" \
  -F "category=policies" \
  -F 'tags=["hr","handbook"]' \
  -F "scope=organization"

Response 201

{
  "success": true,
  "document": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fileName": "remote-work-policy.pdf",
    "filePath": null,
    "originalStorage": "object-storage",
    "fileSize": 48213,
    "fileType": "pdf",
    "textLength": 9120,
    "chunkCount": 11
  },
  "message": "Document processed successfully"
}

POST/api/knowledge/upload/batchAuthenticated

Uploads up to 10 files in one multipart/form-data request (field name files). Takes the same scope, workspaceId, category and tags fields as a single upload. A file that cannot be read is listed in errors; the others are still added. A file of an unsupported type refuses the whole request with 415, and nothing is added.

Body Parameters

filesfile[]required

Up to 10 documents.

scopestring

Default: "organization"

organization, workspace or personal.

workspaceIdstring (UUID)

Required when scope is workspace.

Request

cURL

curl -X POST https://api.lvng.ai/api/knowledge/upload/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@remote-work-policy.pdf" \
  -F "files=@expense-policy.docx" \
  -F "category=policies" \
  -F "scope=organization"

Response 201

{
  "success": true,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fileName": "remote-work-policy.pdf",
      "fileSize": 48213,
      "fileType": "pdf",
      "textLength": 9120,
      "chunkCount": 11,
      "scope": "organization"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "fileName": "expense-policy.docx",
      "fileSize": 22950,
      "fileType": "docx",
      "textLength": 4410,
      "chunkCount": 6,
      "scope": "organization"
    }
  ],
  "errors": [],
  "successCount": 2,
  "errorCount": 0,
  "message": "Processed 2/2 documents successfully"
}

Documents

GET/api/knowledge/documentsAuthenticated

Lists the documents you can read: your organization's, the open workspace's and your own, newest first.

Query Parameters

limitnumber

Default: 50

Documents per page.

offsetnumber

Default: 0

Documents to skip.

scopestring

Only one scope: organization, workspace or personal.

categorystring

Only this category.

tagstring

Only documents with this tag.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fileName": "remote-work-policy.pdf",
      "fileType": "pdf",
      "category": "policies",
      "tags": ["hr", "handbook"],
      "textLength": 9120,
      "chunkCount": 11,
      "uploadedAt": "2026-10-13T09:58:00.000Z",
      "size": 48213,
      "updated": "2026-10-13T09:58:00.000Z",
      "scope": "organization",
      "metadata": {}
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0,
  "tenantContext": { "customerId": "c0ffee00-1234-4abc-9def-000000000001", "scope": "all" }
}

GET/api/knowledge/document/:idAuthenticated

Returns one document and its passages. Answers 404 when the document does not exist or you cannot read it.

Path Parameters

idstring (UUID)required

The document id.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/document/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "document": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fileName": "remote-work-policy.pdf",
    "fileType": "pdf",
    "category": "policies",
    "tags": ["hr", "handbook"],
    "textLength": 9120,
    "chunkCount": 11,
    "uploadedAt": "2026-10-13T09:58:00.000Z",
    "scope": "organization",
    "metadata": {}
  },
  "chunks": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "text": "All team members may work remotely up to 3 days per week...",
      "chunkIndex": 0,
      "chunkSize": 1000
    }
  ]
}

GET/api/knowledge/document/:id/downloadAuthenticated

Downloads the original file as an attachment. For a document whose original is not kept, it sends the stored text (Content-Type text/plain) under the document's file name.

Path Parameters

idstring (UUID)required

The document id.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/document/{id}/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

Content-Disposition: attachment; filename="remote-work-policy.pdf"
Content-Type: application/octet-stream

<file bytes>

GET/api/knowledge/documents/:id/statusAuthenticated

Says whether a document's passages are stored yet: pending, processing or indexed, with a percentage.

Path Parameters

idstring (UUID)required

The document id.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/documents/{id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "status": "indexed",
  "processingProgress": 100,
  "document": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fileName": "remote-work-policy.pdf",
    "fileType": "pdf",
    "chunkCount": 11,
    "uploadedAt": "2026-10-13T09:58:00.000Z"
  }
}

DELETE/api/knowledge/document/:idAuthenticated

Deletes a document, its passages and its stored original. Answers 404 when the document does not exist or is not yours to delete.

Path Parameters

idstring (UUID)required

The document id.

Request

cURL

curl -X DELETE "https://api.lvng.ai/api/knowledge/document/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "message": "Document deleted: remote-work-policy.pdf"
}

Search

POST/api/knowledge/searchAuthenticated

Finds the passages that contain your query (case does not matter) in the documents you can read, with the document each one comes from.

Body Parameters

querystringrequired

The text to look for.

limitnumber

Default: 10

Maximum passages to return.

scopestring

Only one scope: organization, workspace or personal.

categorystring

Only documents in this category.

tagsstring[]

Only documents with any of these tags.

Request

cURL

curl -X POST https://api.lvng.ai/api/knowledge/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "remote work",
    "limit": 10
  }'

Response 200

{
  "success": true,
  "query": "remote work",
  "results": [
    {
      "document": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fileName": "remote-work-policy.pdf",
        "fileType": "pdf",
        "category": "policies",
        "scope": "organization"
      },
      "chunk": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "text": "All team members may work remotely up to 3 days per week...",
        "chunkIndex": 0
      }
    }
  ],
  "count": 1,
  "tenantContext": { "customerId": "c0ffee00-1234-4abc-9def-000000000001", "scope": "all" }
}

Statistics

GET/api/knowledge/statsAuthenticated

Totals for the documents you can read: documents, passages, characters, and the file types, categories and scopes in use.

Query Parameters

scopestring

Only one scope: organization, workspace or personal.

Request

cURL

curl -X GET "https://api.lvng.ai/api/knowledge/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "documentCount": 12,
  "chunkCount": 214,
  "totalCharacters": 187340,
  "fileTypes": ["pdf", "md", "docx"],
  "categories": ["policies", "general"],
  "scopes": ["organization", "personal"],
  "supportedFormats": [".pdf", ".docx", ".txt", ".md", ".json", ".yaml", ".html"],
  "tenantContext": { "customerId": "c0ffee00-1234-4abc-9def-000000000001", "scope": "all" }
}