ksapi — Python SDK Quickstart
The official Python client for the Knowledge Stack API. One client authenticates with an API key, ingests documents, asks the agent, and streams chat.
The full per-endpoint reference is generated alongside this package under
./docs/.
Install
pip install ksapi
Authenticate
Mint an API key (in the app under API Keys, or POST /v1/api-keys) and pass it
as access_token. The client sends it as Authorization: Bearer <key> on every
request:
import ksapi
from ksapi.api.documents_api import DocumentsApi
config = ksapi.Configuration(
host="https://api.your-host.example",
access_token="sk-user-...", # your API key
)
client = ksapi.ApiClient(config)
# Smoke test — list documents you can access
print(DocumentsApi(client).list_documents(limit=10).total, "documents")
Browser/session callers authenticate with the ks_uat cookie instead:
ksapi.Configuration(host=..., api_key={"cookieAuth": "<ks_uat value>"}).
Ingest a document and wait until it's searchable
Ingestion is asynchronous. Upload, then poll until the active version's pipeline
status is completed — at that point the chunks are embedded and searchable:
import time
from ksapi.api.documents_api import DocumentsApi
docs = DocumentsApi(client)
with open("contract.pdf", "rb") as fh:
created = docs.ingest_document(
file=fh.read(),
path_part_id="<parent-folder-path-part-id>", # a FOLDER
name="contract.pdf",
)
while True:
version = docs.get_document(created.document_id).active_version
meta = version.system_metadata
status = meta.pipeline_state.status if meta and meta.pipeline_state else None
if status in ("completed", "failed"):
break
time.sleep(2)
print("ingestion:", status)
Ask the agent
from ksapi.api.agent_api import AgentApi
from ksapi.models.ask_request import AskRequest
answer = AgentApi(client).agent_ask(AskRequest(prompt="What are the renewal terms?"))
print(answer.text)
Citation-grounded, multi-turn chat runs through threads; each assistant
message exposes content.citations. Stream those tokens live below.
Stream chat responses (SSE)
The agent streams over Server-Sent Events at GET /v1/threads/{thread_id}/stream.
The generated stream_thread() method buffers the whole response, so consume the
stream directly — the body is data: <json> lines terminated by data: [DONE]:
import httpx
def stream_thread(host: str, api_key: str, thread_id: str):
headers = {"Authorization": f"Bearer {api_key}"}
with httpx.Client(base_url=host, headers=headers, timeout=60) as http:
with http.stream("GET", f"/v1/threads/{thread_id}/stream") as response:
for line in response.iter_lines():
if not line.startswith("data:"):
continue # skip event:/id:/keepalive lines
payload = line[len("data:"):].strip()
if payload == "[DONE]":
return
yield payload # JSON event — parse with json.loads()
for event in stream_thread(config.host, "sk-user-...", "<thread-id>"):
print(event)
Errors
Every error response keeps detail and adds a machine-readable code plus the
request_id (also returned as the x-request-id header) — quote it to support:
from ksapi.exceptions import NotFoundException
try:
DocumentsApi(client).get_document("00000000-0000-0000-0000-000000000000")
except NotFoundException as exc:
body = exc.body # {"detail": ..., "code": "not_found", "request_id": "..."}
print(exc.status, body)
The client raises a typed exception per status: BadRequestException (400),
UnauthorizedException (401), ForbiddenException (403), NotFoundException
(404), ConflictException (409), UnprocessableEntityException (422), and
ServiceException (5xx).
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ksapi-2.8.0.tar.gz.
File metadata
- Download URL: ksapi-2.8.0.tar.gz
- Upload date:
- Size: 431.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a8b848baf640c3cbfcae66d142e76246b248608789ea11e5baf67dfba3119045
|
|
| MD5 |
ac7e0e5510541e90a0c82cd0f73020a4
|
|
| BLAKE2b-256 |
90215481a1c5af125a2c68399a4b01a70cfd6af665becf4c00cedf23c5453569
|
File details
Details for the file ksapi-2.8.0-py3-none-any.whl.
File metadata
- Download URL: ksapi-2.8.0-py3-none-any.whl
- Upload date:
- Size: 1.2 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.14.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b0cfcebddd40d4eeadf544a2e30f79994cbe3b99f93746d8e39d2d6cff70d876
|
|
| MD5 |
f03a22032a1bb9e7cf9762f2a7b42586
|
|
| BLAKE2b-256 |
cb2069b9eda93c1c834f2c3d818e85742a5d53f33010f798d31befb1b239dd97
|
