x-cpod-domain: knowledge

Knowledge

Documents, chunks, and entities backing search & retrieval.

Try in explorer client.knowledge

Document

A document indexed for search and RAG.

REST path/api/v1/knowledge/documents

Operations

listgetcreateupdatedelete

SDK

// list — returns only your records; add filters/search:
await client.knowledge.documents.list()

// create:
await client.knowledge.documents.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
account_id	string	Optional account scope.
collection_id	string	Logical grouping, e.g. kb-security, kb-product.
kind	string	Document kind classification.
title	string	Human-readable document title.
description	string	Optional long-form description of the document.
mime_type	string	MIME type of the document bytes.
size_bytes	number	Size of the document in bytes.
file_hash	string	SHA-256 hash of the document bytes, used as a deduplication key.
minio_key	string	MinIO object key for the document bytes. Format: cpod-files/{tenantId}/{collectionId}/{docId}/source.{ext}.
language	string	BCP-47 language tag for the document content.
page_count	number	Number of pages in the document.
extractor	string	Extraction pipeline used to process this document.
extraction_status	string	Current status of the document extraction pipeline.
extracted_at	date-time	ISO 8601 timestamp when extraction completed.
chunk_count	number	Cached count of chunks produced from this document.
embedding_model	string	Embedding model used to generate chunk vectors.
embedding_dimensions	number	Dimensionality of the embedding vectors.
chunk_ids	json	Material list of chunk IDs (also derivable from graph edges).
entity_ids	json	IDs of extracted KnowledgeEntity nodes (kne-<uuid>).
effective_from	date-time	Start of the validity window for policy or contract documents.
effective_to	date-time	End of the validity window for policy or contract documents.
version	string	Document's own version string, independent of the record version header.
parent_document_id	string	ID of the document this one supersedes, if applicable.
acl_scope	string	Access control scope for this document.
acl_allowed_role_ids	json	Role IDs permitted to access this document when aclScope is restricted.
tags	json	Free-form tags for categorisation and search.
status	enum	Lifecycle status of this document record.`activearchiveddraft`

Chunk

A chunk of a Document used at retrieval time.

REST path/api/v1/knowledge/chunks

Operations

listgetcreatedeletesearch

SDK

// list — returns only your records; add filters/search:
await client.knowledge.chunks.list()

// create:
await client.knowledge.chunks.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
document_id	string	ID of the parent Document (doc-<uuid>).
chunk_number	number	Sequential position of this chunk within the parent document.
text	string	Text content of this chunk.
tokens	number	Token count of the chunk text.
vector	json	Embedding vector (Array<Float32, 1536>), HNSW-indexed in ClickHouse.
embedding_model	string	Embedding model used to generate the vector.
chunk_type	string	Structural type of the chunk content.
page_number	number	Page number in the source document where this chunk appears.
header_path	json	Heading hierarchy leading to this chunk, e.g. ["Section 5", "5.2 Access Control"].
prev_chunk_id	string	ID of the preceding chunk in the document, for sequential traversal.
next_chunk_id	string	ID of the following chunk in the document, for sequential traversal.
entity_ids	json	IDs of KnowledgeEntity nodes mentioned in this chunk.
keywords	json	Extracted keywords from the chunk text.
language	string	BCP-47 language tag for this chunk's content.
sensitivity	string	Data sensitivity classification for this chunk.
status	enum	Lifecycle status of this chunk.`activearchivedsuperseded`

KnowledgeEntity

A named entity extracted from documents.

REST path/api/v1/knowledge/entities

Operations

listgetcreateupdatedelete

SDK

// list — returns only your records; add filters/search:
await client.knowledge.entities.list()

// create:
await client.knowledge.entities.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
type	string	Semantic type of this knowledge entity.
domain	string	Knowledge domain this entity belongs to.
name	string	Human-readable display name.
canonical_name	string	Normalised name (lowercased, deduped) used for deduplication.
aliases	json	Alternative names or synonyms for this entity.
description	string	Optional description of this entity.
confidence	number	Extraction confidence score in the range [0, 1].
document_ids	json	IDs of source documents where this entity was mentioned.
chunk_ids	json	IDs of chunks where this entity appears.
attributes	json	Domain-specific attributes, e.g. { severity, cvss_score, mitre_tactic, control_id, ... }.
version_info	string	Version string for versioned entities (e.g. CVE-2024-12345 → 2024-12345).
is_valid	boolean	True until this entity is superseded by a newer version.
last_seen_at	date-time	ISO 8601 timestamp when this entity was last observed in a document.
tags	json	Free-form tags for categorisation.
status	enum	Lifecycle status of this knowledge entity.`activemergedarchived`

Docs

Document

Chunk

KnowledgeEntity