Knowledge

Knowledge packs and their documents.

GET/v1/knowledge/bases

List a knowledge pack's documents

listDocumentsknowledge:readread: 600/min per key

Newest first.

Path parameters

idstringrequired
Knowledge base id (kb_…); the id without its prefix is accepted too.

Query parameters

limitinteger
Page size, 1-200 (default 50).
cursorstring
The nextCursor of the previous page.

Returns

200 A page of documents. A page: data is a list of Document, and nextCursor fetches the next page.

Fields of data

idstringrequired
Document id (doc_…).
pattern `^doc_.*`
knowledgeBaseIdstringrequired
Knowledge base id (kb_…).
pattern `^kb_.*`
namestringrequired
typestring | nullrequired
pdf, txt, md, docx, csv, url or text.
bytesinteger | nullrequired
status"processing" | "ready" | "failed"required
processing until it has been read; then ready, or failed.
chunkCountinteger | nullrequired
How many passages were read from it, once ready.
errorstring | nullrequired
When failed: one plain sentence (the file couldn't be read, took too long, reading is unavailable, or it couldn't be processed).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found gone rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/knowledge/bases/kb_123/documents?limit=20" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const page = await zentiq.listDocuments("kb_123", {
  limit: 20,
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
page = zentiq.list_documents("kb_123", limit=20)

Example answer

Response

{
  "data": [
    {
      "id": "doc_cmfq2b7x10000abcd1234",
      "knowledgeBaseId": "kb_cmfq2b7x10000abcd1234",
      "name": "Zoe",
      "type": "…",
      "bytes": 1,
      "status": "processing"
    }
  ],
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d",
  "nextCursor": null
}

POST/v1/knowledge/bases/{id}/documents

Add a document (a file, an address or text)

createDocumentknowledge:writewrite: 120/min per keyIdempotency-Key

Three ways: a multipart file; or JSON { url }; or JSON { text }. Answers at once with the document processing; poll GET /knowledge/documents/{id}, or subscribe to the knowledge.document.* webhooks. Documents count against the plan (403 upgrade_required).

Path parameters

idstringrequired
Knowledge base id (kb_…); the id without its prefix is accepted too.

Body

urlstring (uri)
A public https address to fetch and read (25 MB at most; every redirect is checked too).
textstring
Text to read (1 MB at most).
at most 1,048,576 characters
namestring
at most 200 characters

Or a multipart/form-data upload:

filestring (binary)required
pdf, txt, md, docx or csv; 25 MB at most.
namestring

Returns

202 Accepted: the document is being read. data is Document.

Fields of data

idstringrequired
Document id (doc_…).
pattern `^doc_.*`
knowledgeBaseIdstringrequired
Knowledge base id (kb_…).
pattern `^kb_.*`
namestringrequired
typestring | nullrequired
pdf, txt, md, docx, csv, url or text.
bytesinteger | nullrequired
status"processing" | "ready" | "failed"required
processing until it has been read; then ready, or failed.
chunkCountinteger | nullrequired
How many passages were read from it, once ready.
errorstring | nullrequired
When failed: one plain sentence (the file couldn't be read, took too long, reading is unavailable, or it couldn't be processed).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found idempotency_conflict idempotency_in_progress gone too_large unsupported_media_type rate_limited server_error

Events

knowledge.document.processed knowledge.document.failed

Request

curl -X POST "https://app.zentiqai.com/v1/knowledge/bases/kb_123/documents" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.createDocument("kb_123", {});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.create_document("kb_123", {})

Example answer

Response

{
  "data": {
    "id": "doc_cmfq2b7x10000abcd1234",
    "knowledgeBaseId": "kb_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "type": "…",
    "bytes": 1,
    "status": "processing"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

POST/v1/knowledge/bases/{id}/search

Search a knowledge pack

searchKnowledgeknowledge:readsearch: 120/min per key

The same look-up a live session makes, on its own: the passages closest to query.

Path parameters

idstringrequired
Knowledge base id (kb_…); the id without its prefix is accepted too.

Body

querystringrequired
at most 4,096 characters
topKinteger
How many passages (default 5).
1-50
minScorenumber
Leave out passages below this similarity (0-1, default 0).
0-1

Returns

200 The closest passages. data is SearchResult.

Fields of data

resultsobject[]required
- documentIdstringrequired
  Document id (doc_…).
  pattern `^doc_.*`
- textstringrequired
- scorenumberrequired
  0-1 similarity (higher is closer).
- metadataobjectrequired
  - pageinteger | nullrequired

Errors

invalid_request unauthorized forbidden upgrade_required not_found gone too_large rate_limited server_error upstream_error

Request

curl -X POST "https://app.zentiqai.com/v1/knowledge/bases/kb_123/search" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "…"
}'

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.searchKnowledge("kb_123", {
  query: "…",
});

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.search_knowledge("kb_123", {
    "query": "…",
})

Example answer

Response

{
  "data": {
    "results": [
      {
        "documentId": "doc_cmfq2b7x10000abcd1234",
        "text": "…",
        "score": 1,
        "metadata": {
          "page": 1
        }
      }
    ]
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/knowledge/documents/{id}

Get a document (poll until it is read)

getDocumentknowledge:readread: 600/min per key

Path parameters

idstringrequired
Document id (doc_…); the id without its prefix is accepted too.

Returns

200 The document. data is Document.

Fields of data

idstringrequired
Document id (doc_…).
pattern `^doc_.*`
knowledgeBaseIdstringrequired
Knowledge base id (kb_…).
pattern `^kb_.*`
namestringrequired
typestring | nullrequired
pdf, txt, md, docx, csv, url or text.
bytesinteger | nullrequired
status"processing" | "ready" | "failed"required
processing until it has been read; then ready, or failed.
chunkCountinteger | nullrequired
How many passages were read from it, once ready.
errorstring | nullrequired
When failed: one plain sentence (the file couldn't be read, took too long, reading is unavailable, or it couldn't be processed).
createdAtstring (date-time)required
ISO 8601 UTC timestamp.
updatedAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found gone rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/knowledge/documents/doc_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.getDocument("doc_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.get_document("doc_123")

Example answer

Response

{
  "data": {
    "id": "doc_cmfq2b7x10000abcd1234",
    "knowledgeBaseId": "kb_cmfq2b7x10000abcd1234",
    "name": "Zoe",
    "type": "…",
    "bytes": 1,
    "status": "processing"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

DELETE/v1/knowledge/documents/{id}

Delete a document

deleteDocumentknowledge:writewrite: 120/min per key

Its passages and its original file go with it.

Path parameters

idstringrequired
Document id (doc_…); the id without its prefix is accepted too.

Returns

200 Deleted. data is object.

Fields of data

deletedtruerequired
idstringrequired
Document id (doc_…).
pattern `^doc_.*`

Errors

invalid_request unauthorized forbidden upgrade_required not_found rate_limited server_error

Request

curl -X DELETE "https://app.zentiqai.com/v1/knowledge/documents/doc_123" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.deleteDocument("doc_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.delete_document("doc_123")

Example answer

Response

{
  "data": {
    "deleted": true,
    "id": "doc_cmfq2b7x10000abcd1234"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}

GET/v1/knowledge/documents/{id}/download

Download a document's original file

downloadDocumentknowledge:readread: 600/min per key

A signed address that works for about ten minutes; never a storage path.

Path parameters

idstringrequired
Document id (doc_…); the id without its prefix is accepted too.

Returns

200 Where to download it. data is DownloadUrl.

Fields of data

urlstringrequired
A short-lived signed address of the original file.
expiresAtstring (date-time)required
ISO 8601 UTC timestamp.

Errors

invalid_request unauthorized forbidden upgrade_required not_found gone rate_limited server_error

Request

curl "https://app.zentiqai.com/v1/knowledge/documents/doc_123/download" \
  -H "Authorization: Bearer $ZENTIQ_API_KEY"

import { Zentiq } from "@zentiq/node";

const zentiq = new Zentiq({ apiKey: process.env.ZENTIQ_API_KEY });
const result = await zentiq.downloadDocument("doc_123");

import os
from zentiq import Zentiq

zentiq = Zentiq(api_key=os.environ["ZENTIQ_API_KEY"])
result = zentiq.download_document("doc_123")

Example answer

Response

{
  "data": {
    "url": "https://www.example.com",
    "expiresAt": "2026-09-25T12:00:00.000Z"
  },
  "error": null,
  "requestId": "req_4f1c2e9a7b3d5e6f7a8b9c0d"
}