VocalDocscontracts 1.65.0

Create a Knowledge base

POST /v1/knowledge-bases

PropertyValue
Operationcreate_knowledge_base
GroupKnowledge bases
Scopeknowledge:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited knowledge.knowledge_base.create (mutation)
Released in1.53.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates a Knowledge base draft at revision 1 with no Source and no version (1.53.0). The embedding Provider must serve the model at its embeddings stage and be allowed by the Compliance profile; every issue is a detail of 422 validation_failed (KnowledgeBaseIssueCode). phi_content: per_person is reserved and refused with capability_not_available.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the knowledge:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/knowledge-bases" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "clinic-patient-faq",
    "embedding": {
      "provider": "mock",
      "model": "<model>"
    }
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: KnowledgeBaseCreateRequest.

FieldTypeRequiredDescription
auto_publishKnowledgeAutoPublishno
chunkingKnowledgeChunkingInputno
descriptionstringno
embeddingKnowledgeEmbeddingInputyes
languageLanguageTagno
nameKnowledgeBaseNameyes
phi_contentKnowledgePhiContentno
retrieval_defaultsKnowledgeRetrievalDefaultsInputno
sensitive_contentKnowledgeSensitiveContentInputno

Responses

StatusContent typeShapeError codes
201application/jsonKnowledgeBase
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed, capability_not_available
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is KnowledgeBase.

FieldTypeRequiredDescription
active_versioninteger or nullyesThe version bindings that track active resolve at dispatch, or null when none is active.
archived_atTimestamp or nullyesWhen DELETE archived the Knowledge base, or null. An archived Knowledge base takes no write, upload, sync or publish (409 knowledge_base_archived).
auto_publishKnowledgeAutoPublishyes
chunkingKnowledgeChunkingyes
created_atTimestampyes
descriptionstring or nullyes
document_countintegernoThe Documents of the Knowledge base that are not removed, whatever their status (1.54.0); absent from an api before 1.54.0.
embeddingKnowledgeEmbeddingyes
idKnowledgeBaseIdyes
languageLanguageTagyes
latest_versioninteger or nullyesThe highest published version, or null before the first publish.
nameKnowledgeBaseNameyes
object"knowledge_base"yes
organization_idOrganizationIdyes
phi_contentKnowledgePhiContentyes
retrieval_defaultsKnowledgeRetrievalDefaultsyes
revisionintegeryesCounts writes to the draft; returned as the ETag and required in If-Match.
sensitive_contentKnowledgeSensitiveContentyes
source_countintegernoThe Sources of the Knowledge base that are not deleted (1.54.0); absent from an api before 1.54.0.
updated_atTimestampyes