Knowledge Platform — APIs

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

ArtifactService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/artifacts/{artifactId}	GetArtifact	factory.artifacts.read	read	natural	GW-03	Metadata, lineage, version chain position and a scoped download reference.
GET	/factory/artifacts/{artifactId}/preview	PreviewArtifact	factory.artifacts.read	read	natural	GW-03	Rendered preview (diff, document, report) under the caller's scope; projection, never a second copy.
GET	/factory/artifacts/{artifactId}/versions	ListArtifactVersions	factory.artifacts.read	read	natural	GW-03	The version chain of an artifact.
GET	/factory/runs/{runId}/artifacts	ListRunArtifacts	factory.runs.read	read	natural	GW-03	Artifacts produced by a run with their validation state.
POST	/factory/projects/{projectId}/artifacts/export	ExportArtifacts	factory.artifacts.admin	external	key-header	GW-03	Export a project's artifacts, lineage and metadata in open formats (D31, XL-14).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Artifacts	Store	client	internal	shared-write	Store content by hash with metadata, producer and lineage; idempotent on tenant and hash within a chain.
Artifacts	Fetch	server	internal	read	Stream content of an artifact under scope.
Artifacts	RecordValidation	none	internal	shared-write	Attach a validator verdict to an artifact.

ContextBuilderService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/runs/{runId}/context-snapshots	ListContextSnapshots	factory.runs.read	read	natural	GW-03	Context snapshots of a run with status, budget and counts.
GET	/factory/context-snapshots/{contextSnapshotId}	GetContextSnapshot	factory.runs.read	read	natural	GW-03	Why each item was selected or dropped: sections, scores, citations, compression and budget (FUX-06).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
ContextAssembly	Assemble	none	internal	read	Build the context for an attempt within its token budget and scope; returns the snapshot id and the content reference (context-snapshot-v1).

MemoryPromotionService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/memory	ListMemory	factory.memory.read	read	natural	GW-03	Memories in scope by class, state and trust tier with provenance.
GET	/factory/memory/{memoryId}	GetMemory	factory.memory.read	read	natural	GW-03	A memory with its evidence, review decisions and usage.
POST	/factory/memory/{memoryId}/promote	PromoteMemory	factory.memory.review	publication	natural	GW-03	Promote a reviewed candidate (approval-gated action of class publication bound to the content hash).
POST	/factory/memory/{memoryId}/archive	ArchiveMemory	factory.memory.review	shared-write	natural	GW-03	Archive a memory (reviewer or workspace admin).
PUT	/factory/memory/consent	SetMemoryConsent	factory.memory.admin	production	natural	GW-03	Grant or revoke the tenant's consent for Shared memory and cross-tenant patterns (Platform admin).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Memory	RetrieveMemory	none	internal	read	Promoted memories in scope ranked for a task; used by context assembly (episodic and semantic sections).
Memory	Observe	none	internal	shared-write	Submit observations from a completed attempt or run as candidate memories.

KnowledgeHost

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/knowledge/health	KnowledgeHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health (knowledge store, vector index, blob store, model gateway for embeddings, source connectors).
GET	/knowledge/meta/modules	KnowledgeModules	factory.meta.read	read	natural	GW-03	Modules, vector profile in use (ADR-0013) and embedding profile versions of the indexes.

KnowledgeIngestionService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
POST	/factory/knowledge/sources	RegisterSource	factory.knowledge.admin	shared-write	key-header	GW-03	Register a source with kind, reference, extractor, classification, ACL mapping and sync policy (Workspace admin).
GET	/factory/knowledge/sources	ListSources	factory.knowledge.read	read	natural	GW-03	Sources in scope with state, last snapshot and staleness.
POST	/factory/knowledge/sources/{sourceId}/sync	SyncSource	factory.knowledge.admin	shared-write	key-header	GW-03	Take a new snapshot now.
DELETE	/factory/knowledge/sources/{sourceId}	DeleteSource	factory.knowledge.admin	production	natural	GW-03	Delete a source and every derived item with deletion lineage (D31).
GET	/factory/knowledge/snapshots/{snapshotId}	GetSnapshot	factory.knowledge.read	read	natural	GW-03	Pipeline state, counts and stage timings of a snapshot.
PUT	/factory/projects/{projectId}/knowledge/collections/{name}	SetCollection	factory.knowledge.admin	shared-write	natural	GW-03	Define a collection of sources with its embedding profile version.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Ingestion	GetSourceScope	none	internal	read	Sources and collections a scope may retrieve from, with ACL scopes; used by retrieval and context assembly.

RepositoryIntelligenceService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/repositories/{sourceId}/indexes	ListRepositoryIndexSets	factory.knowledge.read	read	natural	GW-03	Index sets per revision with state and counts.
POST	/factory/repositories/{sourceId}/indexes/rebuild	RebuildRepositoryIndexes	factory.knowledge.admin	shared-write	key-header	GW-03	Rebuild the index set of the latest snapshot.

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
RepositoryIntelligence	ListFiles	none	internal	read	Tool list_files: file tree at a revision with filters.
RepositoryIntelligence	SearchText	none	internal	read	Tool search_text: full-text search within a repository revision with ranges.
RepositoryIntelligence	SearchSymbols	none	internal	read	Tool search_symbols: symbols by name, kind and container.
RepositoryIntelligence	FindReferences	none	internal	read	Tool find_references: references and callers of a symbol.
RepositoryIntelligence	ReadRange	none	internal	read	Tools read_file and read_range: content by path and line range from the snapshot, never whole repositories.
RepositoryIntelligence	GetDependencies	none	internal	read	Tool get_dependencies: project, package, call and test-coverage edges of a path or symbol.
RepositoryIntelligence	GetHistory	none	internal	read	Tools get_git_diff, git_status (read side) and ownership: history, churn and owners of a path.

VectorMemoryService

REST (public endpoints need a scope; every call carries trusted tenant and project scope)

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
POST	/factory/knowledge/search	Search	factory.knowledge.read	read	natural	GW-03	Hybrid retrieval (vector, full-text, symbol, metadata, graph, temporal) under the caller's scope with citations; the Studio and CLI knowledge search.
POST	/factory/knowledge/graph/query	QueryGraph	factory.knowledge.read	read	natural	GW-03	Federated query over graph domains with temporal filters; returns facts with provenance and trust tier.
GET	/factory/knowledge/collections/{collectionId}/indexes	ListIndexRevisions	factory.knowledge.read	read	natural	GW-03	Index revisions of a collection with state, counts and profile versions.
POST	/factory/knowledge/collections/{collectionId}/indexes/rebuild	RebuildIndexes	factory.knowledge.admin	shared-write	key-header	GW-03	Rebuild indexes from published snapshots (after an embedding profile change or a restore).

gRPC (code-first, internal)

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Retrieval	Retrieve	none	internal	read	Scoped hybrid retrieval for context assembly and the knowledge-search tool; returns cited candidates with ranking signals.
Retrieval	ExpandGraph	none	internal	read	Neighbours of a set of entities in one or more graph domains with temporal validity.