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

POST /v1/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.

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

A knowledge base.

knowledge_base_idstring · uuidRequired
connection_idstring · uuid · nullableRequired
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
connection_source_idsstring[]Required
source_file_authorization_enabledbooleanRequired
connection_provider_typestring · nullableOptional
is_emptybooleanOptionalDefault: true
total_sizeintegerOptional

Total size of all files in the knowledge base, in bytes.

Default: 0
total_filesintegerOptional

Total number of files in the knowledge base.

Default: 0
total_indexed_filesintegerOptional

Total number of successfully indexed files.

Default: 0
total_error_filesintegerOptional

Total number of files that failed indexing.

Default: 0
last_synced_atstring · date-time · nullableOptional

Timestamp when the knowledge base was last successfully synced from its source

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base
descriptionstring · max: 2048OptionalDefault: ""
org_idstringRequired
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:
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:
post/v1/knowledge-bases
curl
curl --fail-with-body -sS \
  "$STACKAI_BASE_URL/v1/knowledge-bases" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
{
  "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_id": "text",
  "role": "viewer",
  "org_level_role": "viewer",
  "user_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  },
  "dataloader_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  }
}

Last updated

Was this helpful?