Knowledge Base API

The Knowledge Base API lets external systems upload documents to a Gendial knowledge base, query it directly, and delete documents. It is useful for synchronizing internal documents or letting a business application post-process retrieved context and generate the final answer itself.

Prerequisites

Create a knowledge base in Gendial.
In the knowledge base settings, view or generate its API key. This key authenticates access to that knowledge base; it is not a user login token.
Record the knowledge base ID (libId).
Make sure the required vectorization or knowledge-graph configuration is complete. The direct query endpoint currently supports vector and knowledge-graph libraries; direct file-library queries are not supported.

Send the API key as a Bearer token:

http

Authorization: Bearer <library-api-secret>
Content-Type: application/json

All requests use the backend /api path. Replace https://your-gendial.example.com in the examples with your Gendial service URL.

Base URL and authentication

The endpoints documented here are relative to the Gendial backend base URL:

POST /api/ingest
POST /api/query
DELETE /api/ingest

The request body must be JSON. The API key belongs to one knowledge base and is checked against the libId in the request.

Upload or update a document

`POST /api/ingest`

This endpoint creates a document or accepts an update and queues it for asynchronous knowledge-base processing.

Field	Type	Required	Description
`libId`	string	Yes	Knowledge base ID, 1–48 characters.
`docId`	string	Yes	Document ID, 1–48 characters. Keep it stable when updating a document.
`docName`	string	Yes	Document name, 1–1024 characters. It is also used to find a document with the same name.
`content`	string	No	Text content, up to 10 MB. The complete JSON request body is also limited to approximately 10 MB. Used when `fileUrl` is not provided.
`fileUrl`	string	No	Externally accessible file URL. Takes precedence over `content`.
`docDesc`	string	No	Document description, 1–1024 characters.
`docAlias`	string	No	Request field, 1–1024 characters. In create, `fileUrl`, or text-overwrite mode the server currently replaces it with `docName`; appending to an existing text document does not update the alias.
`overwrite`	boolean	No	Applies only to text-content mode. Set to `true` to replace existing content; by default, text is appended to an existing document.

In normal use, provide either content or fileUrl. When fileUrl is provided, the server downloads the file and always overwrites a matching document; the file type is inferred from the docName extension, and the server sets docAlias to docName. When content is used, the document is treated as plain text. If a matching document exists and overwrite is not true, the new content is appended to the existing content; when a document is created or overwritten, the server also sets docAlias to docName.

Text content

bash

curl -X POST 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docId": "product-guide-v1",
    "docName": "product-guide.txt",
    "content": "Product: Example Product\nVersion: 1.0",
    "docDesc": "Example product user guide",
    "overwrite": true
  }'

External file URL

bash

curl -X POST 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docId": "annual-report-2025",
    "docName": "annual-report-2025.pdf",
    "fileUrl": "https://files.example.com/annual-report-2025.pdf",
    "docDesc": "2025 annual report"
  }'

A successful response means that the request was accepted:

json

{
  "error": "",
  "data": {}
}

It does not mean that parsing or vectorization has finished. Use your own task-status mechanism or a later query to confirm that processing is complete.

Query a knowledge base directly

`POST /api/query`

This endpoint performs knowledge-base retrieval only. It does not generate a final answer from the retrieved context. One request can query one knowledge base; vector and knowledge-graph libraries are currently supported. Direct file-library queries are not currently supported; the caller can sort, filter, combine, or send the retrieved context to another model.

Field	Type	Required	Description
`libId`	string	Yes	Knowledge base ID, 1–48 characters.
`query`	string	Yes	User question or search text, 1–1024 characters.
`retrieveDocCount`	integer	Yes	Requested number of documents/results to retrieve.
`enhanceContext`	boolean	No	Also include context before and after each matched chunk.
`retrieveDocThreshold`	number	No	Maximum accepted L2 distance for vector retrieval; lower values are more restrictive. Pass a positive number; due to the server's current defaulting logic, `0` falls back to `1.5`.
`libraryLlmModel`	string	No	1–256 characters. The current direct-query endpoint does not use this field for reranking; it is retained only for request compatibility.
`retrieveScoreThreshold`	number	No	File-library retrieval threshold field. Direct file-library queries are not currently supported, so do not rely on this field.

bash

curl -X POST 'https://your-gendial.example.com/api/query' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "query": "How long is the warranty for the example product?",
    "retrieveDocCount": 4,
    "enhanceContext": true,
    "retrieveDocThreshold": 1.5
  }'

The successful response has this outer structure:

json

{
  "error": "",
  "data": [
    {
      "libId": "library-id",
      "libName": "Product Knowledge Base",
      "docResults": [
        {
          "docId": "product-guide-v1",
          "docName": "product-guide.txt",
          "trunkResults": [
            {
              "text": "Matched text chunk",
              "context": "Context including surrounding text",
              "similarity": 0.91
            }
          ]
        }
      ]
    }
  ]
}

Common response fields are:

Knowledge-base item: libId, libName, libType, libDesc, embeddingModel, score, and docResults.
Document item: docId, docName, docAlias, docDesc, docType, score, and trunkResults.
Text-chunk item: text, context, similarity, score, and won; some results may also include parentTrunkId.

The exact values and scores vary with the retrieval strategy and matches. Do not rely on the example score or on a non-empty result; handle data as an array, including when there are no matches.

Delete a document

`DELETE /api/ingest`

Delete a document and its retrieval data by knowledge base ID and document name.

Field	Type	Required	Description
`libId`	string	Yes	Knowledge base ID, 1–48 characters.
`docName`	string	Yes	Document name, 1–1024 characters.

Request example:

bash

curl -X DELETE 'https://your-gendial.example.com/api/ingest' \
  -H 'Authorization: Bearer <library-api-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "libId": "library-id",
    "docName": "product-guide.txt"
  }'

Successful response:

json

{
  "error": "",
  "data": {}
}

Responses, status codes, and rate limits

Status	Meaning
`200`	Request succeeded. For ingestion, this means the job was accepted, not that asynchronous processing has finished.
`401`	Bearer token is missing, or the API key is invalid.
`404`	The knowledge base or document to delete was not found.
`413`	The JSON request body exceeds the server's approximately 10 MB size limit.
`422`	A request field is missing, has the wrong type, or exceeds its length limit.
`500`	Server-side processing error; do not currently call the direct query endpoint for file libraries.
`429`	The endpoint rate limit was exceeded.

The Knowledge Base API is limited to 20 requests per second. Rate-limit and retry requests in the calling service, and distinguish errors such as 401 and 422 that cannot be fixed by retrying.

Security recommendations

Never commit the API key to a repository or expose it in browser code, logs, or client applications.
Prefer storing the key on your own server and calling the Knowledge Base API from there.
Use separate knowledge bases or key-management policies for different external systems; rotate a key in the knowledge base settings if it is exposed.
fileUrl must be reachable from the Gendial server and should use HTTPS. Do not put long-lived sensitive credentials in URLs that may be logged.
Retrieved context may contain internal knowledge-base content. Apply your own access control and sensitive-data protections before returning it to end users.

Knowledge Base API ​

Prerequisites ​

Base URL and authentication ​

Upload or update a document ​

POST /api/ingest ​

Text content ​

External file URL ​

Query a knowledge base directly ​

POST /api/query ​

Delete a document ​

DELETE /api/ingest ​

Responses, status codes, and rate limits ​

Security recommendations ​

Knowledge Base API

Prerequisites

Base URL and authentication

Upload or update a document

`POST /api/ingest`

Text content

External file URL

Query a knowledge base directly

`POST /api/query`

Delete a document

`DELETE /api/ingest`

Responses, status codes, and rate limits

Security recommendations