For the complete documentation index, see llms.txt. This page is also available as Markdown.

POST /v2/knowledge-bases

Create Knowledge Base

post

Create a new knowledge base.

How to use

Create a named content store, optionally selecting existing connection or website sources. Save knowledge_base_id, then upload or synchronize content. Catalog, source, embedding-model, and sharing policies can affect admission. Read successful resource payloads under data when a body is returned.

Authentication and permissions

Required permissions: kbs.create. Resource and owner access checks also apply.

Prepare request.json

Save the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.

{
  "name": "Support handbook",
  "description": "Approved support policies"
}
Authorizations
AuthorizationstringRequired

Personal API key (sk_...) or supported user access JWT. See Authentication and authorization for endpoint restrictions and scopes. Use exactly one Authorization header.

Body

Payload to create a new knowledge base.

connection_idstring · uuid · nullableOptional
connection_source_idsstring[]Optional
source_file_authorization_enabledbooleanOptionalDefault: false
namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base
descriptionstring · max: 2048OptionalDefault: ""
org_level_rolestring · enum · nullableOptional

A user's role within a knowledge base.

Ordered by privilege for Python comparisons. All four ordering operators are defined explicitly because StrEnum subclasses str: its inherited lexicographic comparisons would otherwise apply, so e.g. max() would pick "viewer" over "admin". The operators only order Python objects; Postgres enum ordering is governed by the declaration order above.

Possible values:
Responses
201

Successful Response

application/json
response_codestring · nullableOptional

Machine-readable response code, when provided.

post/v2/knowledge-bases
curl
curl --fail-with-body -sS \
  "$STACKAI_BASE_URL/v2/knowledge-bases" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
{
  "response_code": "text",
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "data": {
    "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
    "connection_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "connection_source_ids": [
      "text"
    ],
    "website_sources": [
      {
        "source_type": "sitemap",
        "original_search_term": "text",
        "selected_resources": [
          "text"
        ]
      }
    ],
    "source_file_authorization_enabled": true,
    "connection_provider_type": "text",
    "is_empty": true,
    "total_size": 0,
    "total_files": 0,
    "total_indexed_files": 0,
    "total_error_files": 0,
    "last_synced_at": "2026-01-01T00:00:00.000Z",
    "name": "Unnamed Knowledge Base",
    "description": "",
    "indexing_params": {
      "ocr": false,
      "embedding_params": {
        "embedding_model": "text",
        "api_key": "text"
      },
      "chunker_params": {
        "chunk_size": 1500,
        "chunk_overlap": 500,
        "chunker_type": "sentence"
      }
    },
    "org_level_role": "viewer",
    "role": "viewer"
  }
}

Last updated

Was this helpful?