Create Knowledge Base

Endpoint

POST /apiops/projects/{projectName}/knowledge-bases/{name}/

This endpoint is an upsert: if a knowledge base with {name} already exists in the project it is updated in place (its id is reused); otherwise a new knowledge base is created.

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
name	string	Yes	Knowledge base name

Query Parameters

None

Request Body

Full JSON Body Example

{
  "name": "product-docs",
  "description": "Product documentation knowledge base",
  "vectorDbRef": "qdrant-main",
  "embeddingProviderRef": "openai-embeddings",
  "collectionName": "product_docs",
  "chunkSize": 1000,
  "chunkOverlap": 200,
  "embeddingModelId": "text-embedding-3-small"
}

Request Body Fields

Field	Type	Required	Default	Description
name	string	No	path name	Knowledge base name. May be omitted (falls back to the path variable). If provided, it must match the path name (case-insensitive).
description	string	No	-	Free-text description
vectorDbRef	string	No	-	Name reference to the VectorDB connection backing this knowledge base
embeddingProviderRef	string	No	-	Name reference to the LLM provider used for embeddings
collectionName	string	No	-	Vector store collection/index name
chunkSize	integer	No	1000	Token count per chunk. An omitted/zero value keeps the default.
chunkOverlap	integer	No	200	Overlap tokens between consecutive chunks. An omitted/zero value keeps the default.
embeddingModelId	string	No	-	Embedding model identifier

Notes

• projectId in the body is ignored — the project is always taken from the URL path (a caller cannot smuggle a foreign project through the body).
• id, status, docCount, chunkCount, createdAt and updatedAt are server-controlled. On create, status defaults to ACTIVE. On upsert-update, counters and status are preserved server-side.

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true
  }
}

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Knowledge base name can not be empty!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Knowledge base name in path (product-docs) does not match name in body (other-name)!"
}

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/knowledge-bases/product-docs/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "description": "Product documentation knowledge base",
    "vectorDbRef": "qdrant-main",
    "embeddingProviderRef": "openai-embeddings",
    "collectionName": "product_docs",
    "chunkSize": 1000,
    "chunkOverlap": 200,
    "embeddingModelId": "text-embedding-3-small"
  }'

Notes and Warnings

• Upsert Semantics: Re-posting an existing name updates the knowledge base in place; the id is reused. Use this to make CI/CD applies idempotent.
• Name Match: If the body contains a name, it must match the path name (case-insensitive); a mismatch returns 400 Bad Request.
• Project From Path Only: The body projectId is never trusted; the resolved project from the URL is always used.
• Server-Controlled Fields: status, docCount and chunkCount cannot be set via this endpoint; they are maintained by the indexing pipeline.
• Chunk Defaults: chunkSize defaults to 1000 and chunkOverlap to 200 when omitted or zero.
• Permissions: Requires AI_DEVELOPMENT + MANAGE permission in the project.

Related Documentation

• Update Knowledge Base - Update an existing knowledge base
• Get Knowledge Base - Get a single knowledge base by name
• Upload Document - Add a document to this knowledge base
• Knowledge Bases API - Resource overview