AI Knowledge API

Version applicability

This page documents AI Knowledge API in kis.ai release 1.1.7. The service’s runtime HTTP paths are unversioned — a /1.1.6/ documentation URL does not imply a /v1/ segment on the API itself.

Before you call

Tenancy headers, bearer authentication, the error envelope and the health probes are the same across every kis.ai service — see API conventions. This page documents what is specific to this block.

Indexing and search across lexical, semantic and hybrid backends.

For concepts and configuration see the block documentation.

Indexing

Endpoint	Purpose
POST /index/{backend}/{collection}	Index one document
POST /index/all/{backend}/{collection}	Index and refresh the whole collection
POST /bulk/{backend}/{collection}	Bulk index
DELETE /index/{backend}/{collection}	Delete from a collection

{
  "docid": "01JB7CY1Q6R0GK09RZAVDQGF11",
  "doctype": "company",
  "contenttype": "text",
  "document": { "name": "kis.ai", "legalname": "kis.ai LLC" }
}

docid is yours to choose and is the idempotency key — re-indexing the same docid replaces the document rather than duplicating it. Use a stable identifier from your own system; a generated one doubles your corpus on every reindex.

Embeddings are generated on the way in for any field declared semantically searchable, so you index documents rather than vectors.

Searching

{
  "query": "connection keeps dropping",
  "mode": "hybrid",
  "limit": 5,
  "filter": { "category": "networking" }
}

Field	Notes
query	The search text
mode	lexical, semantic, hybrid or entity
limit	Maximum results
filter	Facet constraints, applied during the search, not after
offset	Pagination

Filtering during the search rather than after it matters for correctness as much as speed: a post-filter can turn limit: 10 into two results, while an applied filter returns ten matching ones.

{
  "results": [
    {
      "docid": "01JB7CY1Q6R0GK09RZAVDQGF11",
      "score": 0.94,
      "data": { "name": "Appleby Industries" },
      "meta": { "match": "name matched" }
    }
  ]
}

meta.match says why something ranked where it did — which is what you need when debugging a bad answer three layers up in a bot.

Introspection

Endpoint	Purpose
GET /list/backends	Backends available in this deployment
GET /list/documents	Collections visible to the tenant

A collection missing from /list/documents after a deploy means its definition did not load — a quieter failure than an indexing error.

Bulk results

Bulk operations report per-document outcomes. A 200 does not mean every document landed; check the response and replay the failures.

Tenancy

Every request carries the platform tenancy headers — X-Kis-Tenant, X-Kis-Product and X-Kis-Environment. They are the partition key for storage, quotas and audit, so a request without them is rejected rather than served against a default tenant.

Errors

Errors use the platform’s structured error body: a stable code, a human-readable message, and the request id to correlate against logs and audit.

Authentication

Every route requires a bearer token:

Authorization: Bearer <token>

The health and readiness probes are the only unauthenticated surface.

Tenancy

The four CPET headers scope every backend, document and search. The semantic index is partitioned by CPET, so the same document id in two tenants is two documents.

Errors

Status	Meaning
400	Request parse or validation failure, or an unknown backend
401	Missing or invalid token, as plain text
404	No such backend or document
500	Unexpected server error, or an embedding provider failed