Skip to main content
This guide walks you through the four core actions of the Knowledge Stack API: getting a key, ingesting a document, searching it, and starting an AI conversation. Prerequisites: You need an existing Knowledge Stack account and at least one tenant. If you don’t have one yet, reach out to your account administrator.
1

Get an API key

Create an API key to authenticate your requests. You’ll need an existing token (from signing in) to create your first key — use POST /v1/auth/pw/signin to get one.Once you have a token, create a key:
curl -X POST https://api-staging.knowledgestack.ai/v1/api-keys \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart-key"}'
Response:
{
  "id": "key_01j9abc123",
  "name": "quickstart-key",
  "key": "ks_live_abcdef1234567890",
  "created_at": "2025-01-15T10:00:00Z"
}
Copy the key value — it’s only shown once. Use it as <API_KEY> in the steps below.
Store your API key securely. Anyone with the key can make API calls on your behalf.
2

Ingest a document

Upload a document for Knowledge Stack to process. The ingest endpoint accepts a file upload and optional metadata. Knowledge Stack chunks and indexes the document automatically.
curl -X POST https://api-staging.knowledgestack.ai/v1/documents/ingest \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@/path/to/your/document.pdf" \
  -F 'metadata={"title":"Getting Started Guide","folder_path":"/quickstart"}'
Response:
{
  "document_id": "doc_01j9xyz789",
  "version_id": "ver_01j9xyz790",
  "status": "processing",
  "workflow_id": "wf_01j9xyz791"
}
The document is processed asynchronously. The workflow_id lets you track progress.
Processing typically completes within seconds for small documents. You can poll GET /v1/workflows/{workflow_id} to check when the status changes to completed.
Check the workflow status:
curl https://api-staging.knowledgestack.ai/v1/workflows/wf_01j9xyz791 \
  -H "Authorization: Bearer <API_KEY>"

{
  "workflow_id": "wf_01j9xyz791",
  "status": "completed",
  "completed_at": "2025-01-15T10:00:05Z"
}
Once the status is completed, the document’s chunks are ready to search.
3

Search your knowledge base

Run a semantic search against your ingested documents. Knowledge Stack ranks chunks by relevance to your query.
curl -X POST https://api-staging.knowledgestack.ai/v1/chunks/search \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I get started?",
    "limit": 5
  }'
Response:
{
  "results": [
    {
      "chunk_id": "chk_01j9aaa111",
      "score": 0.94,
      "content": "To get started, first create an API key from your dashboard...",
      "document_id": "doc_01j9xyz789",
      "document_title": "Getting Started Guide"
    },
    {
      "chunk_id": "chk_01j9aaa112",
      "score": 0.87,
      "content": "Once you have your key, you can begin ingesting documents...",
      "document_id": "doc_01j9xyz789",
      "document_title": "Getting Started Guide"
    }
  ],
  "total": 2
}
Each result includes a relevance score between 0 and 1, the chunk text, and the source document. Higher scores indicate stronger semantic matches.
Use the parent_path_ids field to scope search to a specific folder. This is useful when you have documents from different teams or topics.
4

Create a thread and ask a question

Threads let you have a multi-turn AI conversation grounded in your documents. Create a thread, send a user message, and Knowledge Stack retrieves relevant chunks and generates a response.Create a thread:
curl -X POST https://api-staging.knowledgestack.ai/v1/threads \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first conversation"
  }'

{
  "id": "thr_01j9bbb222",
  "title": "My first conversation",
  "created_at": "2025-01-15T10:01:00Z"
}
Send a message:
curl -X POST https://api-staging.knowledgestack.ai/v1/threads/thr_01j9bbb222/user_message \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "What does the getting started guide cover?"
  }'

{
  "workflow_id": "thread-agent:01929abc-..."
}
Stream the AI response:
curl https://api-staging.knowledgestack.ai/v1/threads/thr_01j9bbb222/stream \
  -H "Authorization: Bearer <API_KEY>"
The response streams as server-sent events. Each event contains a chunk of the AI’s reply along with citations pointing back to the source documents.
data: {"delta": "The getting started guide covers ", "citations": []}
data: {"delta": "API key creation, document ingestion, ", "citations": [{"chunk_id": "chk_01j9aaa111"}]}
data: {"delta": "semantic search, and AI threads.", "citations": []}
data: [DONE]
Threads maintain conversation history. You can call POST .../user_message again to continue the conversation with follow-up questions.

​
What’s next

You’ve completed the core Knowledge Stack workflow. From here, you can:

Organize with folders

Structure your knowledge base with folders and path-based organization.

Set up permissions

Control which users and groups can access which documents.

Build workflows

Automate ingestion pipelines with custom workflow definitions.

API reference

Full reference for every endpoint, request body, and response schema.