APIs¶

Target Architecture — Final-State Design

This page documents the final-state API surface of the Knowledge Platform. All endpoints honour the cross-cutting metadata fields, enforce tenant isolation, and pass through Knowledge Governance before returning content.

The Knowledge Platform exposes 14 public REST endpoints under the /knowledge prefix, plus internal gRPC contracts for hot paths. The public surface is grouped into four capability areas: Search, Context, Ingestion, and Governance. All endpoints are versioned, authenticated, tenant-scoped, and traced.

API Surface Layers¶

Layer	Purpose	Transport	Consumers
Public REST	The 14 documented endpoints below	HTTPS / JSON	Agent Mesh, Control Plane, Factory Studio, external platforms
Internal gRPC	Low-latency hot paths (embedding, context fan-out)	gRPC / protobuf	Knowledge Platform services only
MCP tools	Knowledge tools for agents	`ConnectSoft.Extensions.ModelContextProtocol`	Microsoft Agent Framework agents
Events	Asynchronous integration	MassTransit / Azure Service Bus	All platforms (see Events)

Authorization¶

Authentication — OAuth2 / OpenID Connect bearer tokens issued by the Control Plane identity provider; service-to-service calls use managed identities.
Tenant scoping — every request must resolve a tenantId (from token claim); handlers reject cross-tenant access.
Memory access policy — read endpoints that return knowledge content (search/*, context/build, context/{id}) invoke MemoryPolicyService to evaluate a MemoryAccessPolicy. Sources the caller is not entitled to are excluded or redacted, and a MemoryAccessDecision + MemoryAccessAudit are recorded.
Scopes — coarse scopes gate the surface: knowledge.read, knowledge.ingest, knowledge.govern.

Versioning¶

Endpoints are versioned via the Accept header (application/vnd.connectsoft.knowledge.v1+json); the default is the latest stable major.
Request/response bodies are additively evolved; breaking changes introduce a new major and a parallel route lifetime window.
Event contracts version independently per the event envelope rules.

gRPC¶

Internal hot paths are exposed as gRPC services for the ContextBuilderService fan-out and embedding pipeline:

knowledge.v1.VectorMemory     // SemanticSearch, HybridSearch, Upsert
knowledge.v1.KnowledgeGraph   // QueryNeighborhood, Project
knowledge.v1.Embedding        // Embed, EmbedBatch
knowledge.v1.MemoryPolicy     // Evaluate

These mirror the REST contracts but use protobuf for low-latency, high-throughput context assembly. They are not exposed outside the platform network boundary.

Search APIs¶

`POST /knowledge/search/semantic`¶

Dense-vector semantic search over embedded knowledge. Owned by VectorMemoryService (via KnowledgeSearchService facade).

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "query": "How did we implement idempotent reservation creation?",
  "scope": ["project", "boundedContext:Reservations"],
  "kinds": ["DecisionRecord", "CodeSymbol", "ServiceBlueprint"],
  "topK": 10,
  "minScore": 0.72,
  "traceId": "trace-9f1c2b7d"
}

Response:

{
  "results": [
    {
      "contextSourceId": "src-aa01",
      "kind": "DecisionRecord",
      "ref": "art-decision-idempotency-14",
      "title": "Idempotency keys for reservation commands",
      "score": 0.91,
      "classification": "Internal",
      "snippet": "Reservation creation derives an idempotency key from ...",
      "origin": "semantic"
    }
  ],
  "tookMs": 38,
  "policyDecisionId": "mad-7781"
}

`POST /knowledge/search/hybrid`¶

Fuses dense-vector and structured-metadata retrieval, then re-ranks. Best for queries that combine meaning with hard filters.

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "query": "retry policy for payment webhooks",
  "filters": {
    "artifactType": ["ServiceBlueprint", "SourceFile"],
    "moduleId": "module-payments-api",
    "classification": ["Public", "Internal"]
  },
  "topK": 15,
  "fusion": "reciprocalRankFusion",
  "traceId": "trace-9f1c2b7d"
}

Response: same results[] shape as semantic search, with origin of semantic, metadata, or fused, plus a rankSignals block per result.

`POST /knowledge/search/metadata`¶

Pure structured search over the metadata index. Owned by MetadataIndexService.

Request:

{
  "tenantId": "connectsoft",
  "filters": {
    "projectId": "proj-booking-saas",
    "artifactType": "PullRequest",
    "status": "Validated",
    "createdAfter": "2026-05-01T00:00:00Z"
  },
  "sort": [{ "field": "createdAt", "direction": "desc" }],
  "page": { "size": 25, "cursor": null }
}

Response: a paged items[] of metadata records plus a nextCursor.

`POST /knowledge/graph/query`¶

Graph neighbourhood and path queries over the knowledge graph. Owned by KnowledgeGraphService.

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "start": { "nodeType": "Module", "ref": "module-reservations-api" },
  "traverse": {
    "edgeTypes": ["DERIVED_FROM", "EMITS", "DEPENDS_ON"],
    "direction": "both",
    "maxDepth": 2
  },
  "returnNodeTypes": ["Artifact", "Contract", "DecisionRecord", "RuntimeSignal"],
  "limit": 100
}

Response:

{
  "graphProjectionId": "gp-7781",
  "nodes": [
    { "nodeId": "kn-001", "nodeType": "Artifact", "ref": "art-serviceblueprint-reservations-1", "title": "Reservations service blueprint" }
  ],
  "edges": [
    { "edgeId": "ke-010", "from": "kn-001", "to": "kn-014", "edgeType": "DERIVED_FROM" }
  ]
}

Context APIs¶

`POST /knowledge/context/build`¶

Assemble a governed, budgeted Context Package. The primary entry point for the Agent Mesh. Owned by ContextBuilderService.

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "agentId": "ConnectSoft.Agent.SolutionArchitect",
  "skillId": "ConnectSoft.Skill.DesignServiceBlueprint",
  "taskId": "task-4d21",
  "traceId": "trace-9f1c2b7d",
  "intent": "Design the reservations service blueprint",
  "scope": ["project", "boundedContext:Reservations"],
  "retrieval": {
    "semantic": true,
    "graph": true,
    "metadata": true,
    "tokenBudget": 16000,
    "maxSources": 40
  },
  "pinned": ["art-domainmodel-7c"]
}

Response:

{
  "contextPackageId": "ctx-31f8",
  "contextBuildRequestId": "ctxreq-19a2",
  "tenantId": "connectsoft",
  "traceId": "trace-9f1c2b7d",
  "createdAt": "2026-06-11T00:00:00Z",
  "ttlSeconds": 1800,
  "tokenBudget": 16000,
  "tokensUsed": 14210,
  "sources": [
    {
      "contextSourceId": "src-001",
      "kind": "DecisionRecord",
      "ref": "art-decision-eventbus-22",
      "title": "Use MassTransit on Azure Service Bus",
      "score": 0.92,
      "classification": "Internal",
      "tokens": 850,
      "origin": "graph"
    },
    {
      "contextSourceId": "src-002",
      "kind": "ServiceBlueprint",
      "ref": "art-serviceblueprint-orders-7",
      "title": "Orders service blueprint (reuse)",
      "score": 0.88,
      "classification": "Internal",
      "tokens": 2200,
      "origin": "semantic"
    }
  ],
  "graphProjectionId": "gp-7781",
  "policyDecisionId": "mad-5521"
}

The built package is cached in Redis under contextPackageId for ttlSeconds, emits ContextPackageBuilt, and is fully auditable. See Context Builder.

`GET /knowledge/context/{contextPackageId}`¶

Retrieve a previously built Context Package (served from the Redis hot cache, or rebuilt if expired). Returns the same body as context/build. A 404 indicates the package never existed; an expired package triggers a transparent rebuild keyed by the original contextBuildRequestId.

Ingestion APIs¶

`POST /knowledge/ingest/artifact`¶

Ingest a factory artifact (the front door, orchestrated by KnowledgeIngestionService).

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "artifactId": "art-serviceblueprint-reservations-1",
  "artifactType": "ServiceBlueprint",
  "version": "1.0.0",
  "contentHash": "sha256:9f86d081...",
  "storageRef": "blob://artifacts/connectsoft/proj-booking-saas/art-serviceblueprint-reservations-1/1.0.0",
  "producedByAgentId": "ConnectSoft.Agent.SolutionArchitect",
  "traceId": "trace-9f1c2b7d"
}

Response:

{
  "memoryRecordId": "mem-55a2",
  "status": "Accepted",
  "dedup": false,
  "pipeline": ["classify", "chunk", "embed", "metadataIndex", "graphProject", "quality"]
}

When contentHash matches an existing record, dedup is true and the embedding/projection stages are skipped.

`POST /knowledge/ingest/repository`¶

Register a source repository for code indexing. Owned by CodebaseKnowledgeService.

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "repository": {
    "ref": "azuredevops://connectsoft/proj-booking-saas/_git/reservations",
    "branch": "main",
    "commit": "a1b2c3d4"
  },
  "indexScope": ["symbols", "dependencies", "embeddings"],
  "traceId": "trace-9f1c2b7d"
}

Response: { "codeIndexJobId": "cij-1201", "status": "Queued" }.

`POST /knowledge/ingest/documentation`¶

Ingest documentation/design docs for grounding. Owned by DocumentationKnowledgeService.

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "source": { "kind": "MkDocsSite", "ref": "blob://docs/proj-booking-saas/site" },
  "chunking": { "strategy": "markdownHeadings", "maxTokens": 800 },
  "traceId": "trace-9f1c2b7d"
}

Response: { "memoryRecordId": "mem-77c1", "status": "Accepted" }.

`POST /knowledge/ingest/prompt`¶

Register a prompt template or record a prompt run. Owned by PromptMemoryService.

{
  "tenantId": "connectsoft",
  "promptTemplateId": "ConnectSoft.Prompt.DesignServiceBlueprint",
  "version": "2.1.0",
  "body": "You are a solution architect. Given {{domainModel}} ...",
  "linkedSkillId": "ConnectSoft.Skill.DesignServiceBlueprint",
  "traceId": "trace-9f1c2b7d"
}

Response: { "promptVersionId": "pv-3301", "status": "Registered" }.

`POST /knowledge/ingest/runtime-signal`¶

Ingest a runtime signal, incident, or feedback item from the Observability & Feedback Platform. Owned by RuntimeMemoryService.

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "moduleId": "module-reservations-api",
  "environment": "prod",
  "signal": {
    "kind": "LatencyRegression",
    "metric": "http.server.duration.p95",
    "value": 820,
    "unit": "ms",
    "linkedArtifactId": "art-serviceblueprint-reservations-1"
  },
  "traceId": "trace-9f1c2b7d"
}

Response: { "runtimeSignalId": "rs-9120", "status": "Recorded" }.

Governance APIs¶

`POST /knowledge/access/evaluate`¶

Evaluate whether a subject may access a set of memory sources. Owned by MemoryPolicyService.

{
  "tenantId": "connectsoft",
  "subject": { "agentId": "ConnectSoft.Agent.SolutionArchitect", "scopes": ["knowledge.read"] },
  "resources": [
    { "ref": "art-decision-pricing-9", "classification": "Confidential" },
    { "ref": "art-serviceblueprint-orders-7", "classification": "Internal" }
  ],
  "purpose": "contextBuild",
  "traceId": "trace-9f1c2b7d"
}

Response:

{
  "policyDecisionId": "mad-5521",
  "decisions": [
    { "ref": "art-decision-pricing-9", "effect": "RedactRequired" },
    { "ref": "art-serviceblueprint-orders-7", "effect": "Allow" }
  ],
  "auditId": "maa-7781"
}

`POST /knowledge/classify`¶

Classify a memory record and assign sensitivity. Owned by MemoryClassificationService.

{
  "tenantId": "connectsoft",
  "memoryRecordId": "mem-55a2",
  "content": "...",
  "hints": { "artifactType": "ServiceBlueprint" }
}

Response: { "classification": "Internal", "confidence": 0.97, "labels": ["architecture", "no-pii"] }.

`POST /knowledge/redact`¶

Produce a redacted projection of content for a given classification and audience. Owned by MemoryRedactionService.

{
  "tenantId": "connectsoft",
  "memoryRecordId": "mem-9911",
  "classification": "Confidential",
  "audience": { "agentId": "ConnectSoft.Agent.TestEngineer" }
}

Response:

{
  "redactedContentRef": "blob://redacted/connectsoft/mem-9911/test-engineer",
  "redactions": [{ "span": "credentials", "reason": "Secret" }],
  "status": "Redacted"
}

Examples: end-to-end agent grounding¶

sequenceDiagram
    participant Agent as Agent (Agent Mesh)
    participant CB as ContextBuilderService
    participant Search as KnowledgeSearchService
    participant Pol as MemoryPolicyService
    Agent->>CB: POST /knowledge/context/build
    CB->>Search: POST /knowledge/search/hybrid (internal)
    CB->>Pol: POST /knowledge/access/evaluate (internal)
    Pol-->>CB: decisions (allow / redact)
    CB-->>Agent: 200 ContextPackage (ctx-31f8)
    Agent->>CB: GET /knowledge/context/ctx-31f8 (on retry)

Hold "Alt" / "Option" to enable pan & zoom

APIs¶

API Surface Layers¶

Authorization¶

Versioning¶

gRPC¶

Search APIs¶

POST /knowledge/search/semantic¶

POST /knowledge/search/hybrid¶

POST /knowledge/search/metadata¶

POST /knowledge/graph/query¶

Context APIs¶

POST /knowledge/context/build¶

GET /knowledge/context/{contextPackageId}¶

Ingestion APIs¶

POST /knowledge/ingest/artifact¶

POST /knowledge/ingest/repository¶

POST /knowledge/ingest/documentation¶

POST /knowledge/ingest/prompt¶

POST /knowledge/ingest/runtime-signal¶

Governance APIs¶

POST /knowledge/access/evaluate¶

POST /knowledge/classify¶

POST /knowledge/redact¶

Examples: end-to-end agent grounding¶

Related Pages¶

`POST /knowledge/search/semantic`¶

`POST /knowledge/search/hybrid`¶

`POST /knowledge/search/metadata`¶

`POST /knowledge/graph/query`¶

`POST /knowledge/context/build`¶

`GET /knowledge/context/{contextPackageId}`¶

`POST /knowledge/ingest/artifact`¶

`POST /knowledge/ingest/repository`¶

`POST /knowledge/ingest/documentation`¶

`POST /knowledge/ingest/prompt`¶

`POST /knowledge/ingest/runtime-signal`¶

`POST /knowledge/access/evaluate`¶

`POST /knowledge/classify`¶

`POST /knowledge/redact`¶