@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/knowledge.md

@@ -0,0 +1,843 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.knowledge`: Knowledge
+
+21 operations (15 read, 6 write).
+
+No hand-written client covers this area. Call it through `g8.api.knowledge.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [knowledge.d.ts](knowledge.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assembleKnowledgeContext`](#op-assembleknowledgecontext) | `POST /api/v1/knowledge/context` | read | `knowledge:read` | Assemble Knowledge Context |
+| [`browseKnowledgeTree`](#op-browseknowledgetree) | `GET /api/v1/knowledge/tree` | read | `knowledge:read` | Browse Knowledge Tree |
+| [`createAuthoredKnowledge`](#op-createauthoredknowledge) | `POST /api/v1/knowledge/authored` | write | `knowledge:write` | Create Authored Knowledge |
+| [`createAuthoredKnowledgeAmendment`](#op-createauthoredknowledgeamendment) | `POST /api/v1/knowledge/authored/{concept_id}/amendments` | write | `knowledge:write` | Create Authored Knowledge Amendment |
+| [`deprecateAuthoredKnowledge`](#op-deprecateauthoredknowledge) | `POST /api/v1/knowledge/authored/{concept_id}/deprecate` | write | `knowledge:write` | Deprecate Authored Knowledge |
+| [`exportKnowledge`](#op-exportknowledge) | `GET /api/v1/knowledge/export` | read | `knowledge:read` | Export Knowledge |
+| [`getKnowledge`](#op-getknowledge) | `GET /api/v1/knowledge/{concept_id}` | read | `knowledge:read` | Get Knowledge |
+| [`getKnowledgeHistory`](#op-getknowledgehistory) | `GET /api/v1/knowledge/{concept_id}/history` | read | `knowledge:read` | Get Knowledge History |
+| [`getKnowledgeStatus`](#op-getknowledgestatus) | `GET /api/v1/knowledge/status` | read | `knowledge:read` | Get Knowledge Status |
+| [`getOntologyDeviations`](#op-getontologydeviations) | `GET /api/v1/knowledge-ontology/deviations` | read | `knowledge:read` | Get Ontology Deviations |
+| [`getOntologyOverview`](#op-getontologyoverview) | `GET /api/v1/knowledge-ontology` | read | `knowledge:read` | Get Ontology Overview |
+| [`getOntologyReadiness`](#op-getontologyreadiness) | `GET /api/v1/knowledge-ontology/readiness` | read | `knowledge:read` | Get Ontology Readiness |
+| [`getStandardOntology`](#op-getstandardontology) | `GET /api/v1/knowledge-ontology/standard` | read | `knowledge:read` | Get Standard Ontology |
+| [`knowledgeSources`](#op-knowledgesources) | `GET /api/v1/knowledge/{concept_id}/sources` | read | `knowledge:read` | Knowledge Sources |
+| [`listKnowledge`](#op-listknowledge) | `GET /api/v1/knowledge` | read | `knowledge:read` | List Knowledge |
+| [`listKnowledgeGovernanceQueue`](#op-listknowledgegovernancequeue) | `GET /api/v1/knowledge-governance` | read | `knowledge:read` | List Knowledge Governance Queue |
+| [`relatedKnowledge`](#op-relatedknowledge) | `GET /api/v1/knowledge/{concept_id}/related` | read | `knowledge:read` | Related Knowledge |
+| [`searchKnowledge`](#op-searchknowledge) | `GET /api/v1/knowledge/search` | read | `knowledge:read` | Search Knowledge |
+| [`updateAuthoredKnowledgeDraft`](#op-updateauthoredknowledgedraft) | `PATCH /api/v1/knowledge/authored/{concept_id}` | write | `knowledge:write` | Update Authored Knowledge Draft |
+| [`upsertOntologyConcept`](#op-upsertontologyconcept) | `PUT /api/v1/knowledge-ontology/{concept_id}` | write | `knowledge:write` | Upsert Ontology Concept |
+| [`verifyAuthoredKnowledge`](#op-verifyauthoredknowledge) | `POST /api/v1/knowledge/authored/{concept_id}/verify` | write | `knowledge:write` | Verify Authored Knowledge |
+
+---
+
+<a id="op-assembleknowledgecontext"></a>
+
+### `g8.api.knowledge.assembleKnowledgeContext(input)`
+
+**Assemble Knowledge Context**
+
+- HTTP: `POST /api/v1/knowledge/context`
+- operationId: `assemble_knowledge_context_knowledge_context_post` (also callable as `g8.api.call("assemble_knowledge_context_knowledge_context_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KnowledgeContextRequest` | yes | Request body; fields below. |
+
+Body fields (`KnowledgeContextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.task` | `string` | yes | min length 1, max length 2000 |
+| `body.entity_concept_ids` | `Array<string>` | no | max items 20 |
+| `body.token_budget` | `integer \| null` | no | min 100, max 100000 |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.assembleKnowledgeContext({ body: { task: "example" } });
+```
+
+---
+
+<a id="op-browseknowledgetree"></a>
+
+### `g8.api.knowledge.browseKnowledgeTree(input?)`
+
+**Browse Knowledge Tree**
+
+- HTTP: `GET /api/v1/knowledge/tree`
+- operationId: `browse_knowledge_tree_knowledge_tree_get` (also callable as `g8.api.call("browse_knowledge_tree_knowledge_tree_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Browse the knowledge tree one folder at a time. FREE.
+
+The structural read `GET /knowledge` cannot do: that one returns a flat
+filtered list, this one walks the hierarchy the brain is actually organised
+into. Page with `cursor`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.parent` | `string \| null` | no | Folder to list. Omit for the root. |
+| `query.cursor` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.browseKnowledgeTree();
+```
+
+---
+
+<a id="op-createauthoredknowledge"></a>
+
+### `g8.api.knowledge.createAuthoredKnowledge(input)`
+
+**Create Authored Knowledge**
+
+- HTTP: `POST /api/v1/knowledge/authored`
+- operationId: `create_authored_knowledge_knowledge_authored_post` (also callable as `g8.api.call("create_authored_knowledge_knowledge_authored_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Write a knowledge concept by hand. FREE.
+
+GOVERNED, not immediate: the entry lands as a draft in the review queue at
+`GET /knowledge/governance` and does not project into the brain's answers
+until it is approved there. Writing here is proposing, not publishing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AuthoredKnowledgeRequest` | yes | Request body; fields below. |
+
+Body fields (`AuthoredKnowledgeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | max length 2000000 |
+| `body.concept_type` | `string` | yes | min length 1, max length 100 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.owner_id` | `string \| null` | no | max length 255 |
+| `body.review_at` | `string (date-time) \| null` | no |  |
+| `body.sources` | `Array<SourceInput>` | no | max items 50 |
+| `body.stale_after` | `string (date-time) \| null` | no |  |
+| `body.visibility` | `string` | no | default `"organization"`, max length 32 |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.createAuthoredKnowledge({
+  body: { body: "example", concept_type: "example", title: "Example" },
+});
+```
+
+---
+
+<a id="op-createauthoredknowledgeamendment"></a>
+
+### `g8.api.knowledge.createAuthoredKnowledgeAmendment(input)`
+
+**Create Authored Knowledge Amendment**
+
+- HTTP: `POST /api/v1/knowledge/authored/{concept_id}/amendments`
+- operationId: `create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post` (also callable as `g8.api.call("create_authored_knowledge_amendment_knowledge_authored__concept_id__amendments_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Propose a revision to an APPROVED concept. FREE.
+
+The approved version keeps answering until the amendment is approved in
+its turn, so proposing one never leaves the brain with a gap.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes | Concept id. |
+| `body` | `AuthoredKnowledgeRequest` | yes | Request body; fields below. |
+
+Body fields (`AuthoredKnowledgeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | max length 2000000 |
+| `body.concept_type` | `string` | yes | min length 1, max length 100 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.owner_id` | `string \| null` | no | max length 255 |
+| `body.review_at` | `string (date-time) \| null` | no |  |
+| `body.sources` | `Array<SourceInput>` | no | max items 50 |
+| `body.stale_after` | `string (date-time) \| null` | no |  |
+| `body.visibility` | `string` | no | default `"organization"`, max length 32 |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.createAuthoredKnowledgeAmendment({
+  path: { concept_id: "id" },
+  body: { body: "example", concept_type: "example", title: "Example" },
+});
+```
+
+---
+
+<a id="op-deprecateauthoredknowledge"></a>
+
+### `g8.api.knowledge.deprecateAuthoredKnowledge(input)`
+
+**Deprecate Authored Knowledge**
+
+- HTTP: `POST /api/v1/knowledge/authored/{concept_id}/deprecate`
+- operationId: `deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post` (also callable as `g8.api.call("deprecate_authored_knowledge_knowledge_authored__concept_id__deprecate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Retire a concept so the brain stops answering from it.
+
+The record and its history survive - this removes it from retrieval, it
+does not delete it. `reason` is required and is kept on the record, which
+is the point: a retired concept with no stated reason is indistinguishable
+from one retired by mistake. Name `superseded_by` when something replaces
+it.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes | Concept id. |
+| `body` | `DeprecateKnowledgeRequest` | yes | Request body; fields below. |
+
+Body fields (`DeprecateKnowledgeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.reason` | `string` | yes | min length 1, max length 2000 |
+| `body.superseded_by` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.deprecateAuthoredKnowledge({ path: { concept_id: "id" }, body: { reason: "example" } });
+```
+
+---
+
+<a id="op-exportknowledge"></a>
+
+### `g8.api.knowledge.exportKnowledge(input?)`
+
+**Export Knowledge**
+
+- HTTP: `GET /api/v1/knowledge/export`
+- operationId: `export_knowledge_knowledge_export_get` (also callable as `g8.api.call("export_knowledge_knowledge_export_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.exportKnowledge();
+```
+
+---
+
+<a id="op-getknowledge"></a>
+
+### `g8.api.knowledge.getKnowledge(input)`
+
+**Get Knowledge**
+
+- HTTP: `GET /api/v1/knowledge/{concept_id}`
+- operationId: `get_knowledge_knowledge__concept_id__get` (also callable as `g8.api.call("get_knowledge_knowledge__concept_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getKnowledge({ path: { concept_id: "id" } });
+```
+
+---
+
+<a id="op-getknowledgehistory"></a>
+
+### `g8.api.knowledge.getKnowledgeHistory(input)`
+
+**Get Knowledge History**
+
+- HTTP: `GET /api/v1/knowledge/{concept_id}/history`
+- operationId: `get_knowledge_history_knowledge__concept_id__history_get` (also callable as `g8.api.call("get_knowledge_history_knowledge__concept_id__history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+A concept's revision history - every authored version, amendment,
+verification and deprecation, newest first. FREE. Page with `cursor`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes | Concept id. |
+| `query.cursor` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getKnowledgeHistory({ path: { concept_id: "id" } });
+```
+
+---
+
+<a id="op-getknowledgestatus"></a>
+
+### `g8.api.knowledge.getKnowledgeStatus(input?)`
+
+**Get Knowledge Status**
+
+- HTTP: `GET /api/v1/knowledge/status`
+- operationId: `get_knowledge_status_knowledge_status_get` (also callable as `g8.api.call("get_knowledge_status_knowledge_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+How complete and how fresh the knowledge brain is. FREE.
+
+Counts by trust tier and freshness, restricted to what this credential's
+record scopes can see.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getKnowledgeStatus();
+```
+
+---
+
+<a id="op-getontologydeviations"></a>
+
+### `g8.api.knowledge.getOntologyDeviations(input?)`
+
+**Get Ontology Deviations**
+
+- HTTP: `GET /api/v1/knowledge-ontology/deviations`
+- operationId: `get_ontology_deviations_knowledge_ontology_deviations_get` (also callable as `g8.api.call("get_ontology_deviations_knowledge_ontology_deviations_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Where your ontology differs from the standard.
+
+A deviation is not automatically wrong - it is where your business calls
+something by its own name. This is the read that tells you which is which.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getOntologyDeviations();
+```
+
+---
+
+<a id="op-getontologyoverview"></a>
+
+### `g8.api.knowledge.getOntologyOverview(input?)`
+
+**Get Ontology Overview**
+
+- HTTP: `GET /api/v1/knowledge-ontology`
+- operationId: `get_ontology_overview_knowledge_ontology_get` (also callable as `g8.api.call("get_ontology_overview_knowledge_ontology_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The org's ontology as it stands.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getOntologyOverview();
+```
+
+---
+
+<a id="op-getontologyreadiness"></a>
+
+### `g8.api.knowledge.getOntologyReadiness(input?)`
+
+**Get Ontology Readiness**
+
+- HTTP: `GET /api/v1/knowledge-ontology/readiness`
+- operationId: `get_ontology_readiness_knowledge_ontology_readiness_get` (also callable as `g8.api.call("get_ontology_readiness_knowledge_ontology_readiness_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+Whether the ontology is complete enough to rely on.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getOntologyReadiness();
+```
+
+---
+
+<a id="op-getstandardontology"></a>
+
+### `g8.api.knowledge.getStandardOntology(input?)`
+
+**Get Standard Ontology**
+
+- HTTP: `GET /api/v1/knowledge-ontology/standard`
+- operationId: `get_standard_ontology_knowledge_ontology_standard_get` (also callable as `g8.api.call("get_standard_ontology_knowledge_ontology_standard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+The standard ontology yours is compared against.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.getStandardOntology();
+```
+
+---
+
+<a id="op-knowledgesources"></a>
+
+### `g8.api.knowledge.knowledgeSources(input)`
+
+**Knowledge Sources**
+
+- HTTP: `GET /api/v1/knowledge/{concept_id}/sources`
+- operationId: `knowledge_sources_knowledge__concept_id__sources_get` (also callable as `g8.api.call("knowledge_sources_knowledge__concept_id__sources_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.knowledgeSources({ path: { concept_id: "id" } });
+```
+
+---
+
+<a id="op-listknowledge"></a>
+
+### `g8.api.knowledge.listKnowledge(input?)`
+
+**List Knowledge**
+
+- HTTP: `GET /api/v1/knowledge`
+- operationId: `list_knowledge_knowledge_get` (also callable as `g8.api.call("list_knowledge_knowledge_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.concept_type` | `string \| null` | no |  |
+| `query.lifecycle` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.listKnowledge();
+```
+
+---
+
+<a id="op-listknowledgegovernancequeue"></a>
+
+### `g8.api.knowledge.listKnowledgeGovernanceQueue(input?)`
+
+**List Knowledge Governance Queue**
+
+- HTTP: `GET /api/v1/knowledge-governance`
+- operationId: `list_knowledge_governance_queue_knowledge_governance_get` (also callable as `g8.api.call("list_knowledge_governance_queue_knowledge_governance_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+What is waiting for review in Knowledge Governance.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.queue` | `string` | no | Which governance queue to read. default `"review"` |
+| `query.cursor` | `string \| null` | no | Opaque cursor from the previous page. |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.listKnowledgeGovernanceQueue();
+```
+
+---
+
+<a id="op-relatedknowledge"></a>
+
+### `g8.api.knowledge.relatedKnowledge(input)`
+
+**Related Knowledge**
+
+- HTTP: `GET /api/v1/knowledge/{concept_id}/related`
+- operationId: `related_knowledge_knowledge__concept_id__related_get` (also callable as `g8.api.call("related_knowledge_knowledge__concept_id__related_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes |  |
+| `query.depth` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `25` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.relatedKnowledge({ path: { concept_id: "id" } });
+```
+
+---
+
+<a id="op-searchknowledge"></a>
+
+### `g8.api.knowledge.searchKnowledge(input)`
+
+**Search Knowledge**
+
+- HTTP: `GET /api/v1/knowledge/search`
+- operationId: `search_knowledge_knowledge_search_get` (also callable as `g8.api.call("search_knowledge_knowledge_search_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `knowledge:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.query` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `10` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<Record<string, unknown>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.searchKnowledge({ query: { query: "example" } });
+```
+
+---
+
+<a id="op-updateauthoredknowledgedraft"></a>
+
+### `g8.api.knowledge.updateAuthoredKnowledgeDraft(input)`
+
+**Update Authored Knowledge Draft**
+
+- HTTP: `PATCH /api/v1/knowledge/authored/{concept_id}`
+- operationId: `update_authored_knowledge_draft_knowledge_authored__concept_id__patch` (also callable as `g8.api.call("update_authored_knowledge_draft_knowledge_authored__concept_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Edit a concept that is still a DRAFT. FREE.
+
+Only while it is unapproved. Once it has been approved, changing it is an
+AMENDMENT - `POST /authored/{id}/amendments` - which is a new governed
+revision rather than an edit in place.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes | Concept id. |
+| `body` | `AuthoredKnowledgeRequest` | yes | Request body; fields below. |
+
+Body fields (`AuthoredKnowledgeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | max length 2000000 |
+| `body.concept_type` | `string` | yes | min length 1, max length 100 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.owner_id` | `string \| null` | no | max length 255 |
+| `body.review_at` | `string (date-time) \| null` | no |  |
+| `body.sources` | `Array<SourceInput>` | no | max items 50 |
+| `body.stale_after` | `string (date-time) \| null` | no |  |
+| `body.visibility` | `string` | no | default `"organization"`, max length 32 |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.updateAuthoredKnowledgeDraft({
+  path: { concept_id: "id" },
+  body: { body: "example", concept_type: "example", title: "Example" },
+});
+```
+
+---
+
+<a id="op-upsertontologyconcept"></a>
+
+### `g8.api.knowledge.upsertOntologyConcept(input)`
+
+**Upsert Ontology Concept**
+
+- HTTP: `PUT /api/v1/knowledge-ontology/{concept_id}`
+- operationId: `upsert_ontology_concept_knowledge_ontology__concept_id__put` (also callable as `g8.api.call("upsert_ontology_concept_knowledge_ontology__concept_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Define or redefine one concept in the ontology.
+
+An upsert: the same `concept_id` twice edits rather than duplicating, which
+makes it safe to retry.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes |  |
+| `body` | `OntologyConceptRequest` | yes | Request body; fields below. |
+
+Body fields (`OntologyConceptRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | min length 1, max length 2000000 |
+| `body.concept_id` | `string` | yes | min length 1, max length 255 |
+| `body.concept_type` | `string` | yes | min length 1, max length 100 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.definition_override` | `string \| null` | no | max length 10000 |
+| `body.extensions` | `Record<string, unknown>` | no |  |
+| `body.ontology` | `Record<string, unknown>` | no |  |
+| `body.relationships` | `Array<OntologyRelationship>` | no | max items 100 |
+| `body.review_at` | `string (date-time) \| null` | no |  |
+| `body.source_owner` | `string \| null` | no | max length 255 |
+| `body.sources` | `Array<OntologySource>` | no | max items 50 |
+| `body.stale_after` | `string (date-time) \| null` | no | After this, the concept is treated as stale. |
+| `body.standard_component_id` | `string \| null` | no | The standard-ontology component this maps to, if any. max length 100 |
+| `body.trust_tier` | `string` | no | How much to trust this definition. Defaults to human-reviewed, matching the app — a concept written through the API is treated as authored, not inferred. default `"human_reviewed"` |
+
+**Returns** `ApiResponse_SettingsPayload_`: the envelope `{ data: SettingsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.upsertOntologyConcept({
+  path: { concept_id: "id" },
+  body: {
+    body: "example",
+    concept_id: "id",
+    concept_type: "example",
+    title: "Example",
+  },
+});
+```
+
+---
+
+<a id="op-verifyauthoredknowledge"></a>
+
+### `g8.api.knowledge.verifyAuthoredKnowledge(input)`
+
+**Verify Authored Knowledge**
+
+- HTTP: `POST /api/v1/knowledge/authored/{concept_id}/verify`
+- operationId: `verify_authored_knowledge_knowledge_authored__concept_id__verify_post` (also callable as `g8.api.call("verify_authored_knowledge_knowledge_authored__concept_id__verify_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `knowledge:write`
+
+Approve or reject a PROPOSED concept. FREE.
+
+Approving makes it answerable - every retrieval grounded on knowledge can
+quote it from this moment - and records `authority` as who vouched for it.
+Rejecting keeps it out of the brain.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.concept_id` | `string` | yes | Concept id. |
+| `body` | `VerifyKnowledgeRequest` | yes | Request body; fields below. |
+
+Body fields (`VerifyKnowledgeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.approve` | `boolean` | yes |  |
+| `body.authority` | `string` | yes | min length 1, max length 255 |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.knowledge.verifyAuthoredKnowledge({
+  path: { concept_id: "id" },
+  body: { approve: true, authority: "example" },
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-ontologyrelationship"></a>
+
+### `OntologyRelationship`
+
+How one concept relates to another. Open-shaped, matching the app.
+
+Type: `Record<string, unknown>`.
+
+<a id="type-ontologysource"></a>
+
+### `OntologySource`
+
+Where a concept came from. Open-shaped, matching the app's `SourceInput`.
+
+Type: `Record<string, unknown>`.
+
+<a id="type-sourceinput"></a>
+
+### `SourceInput`
+
+A citation behind an authored concept.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `resource` | `string` | yes | min length 1, max length 1000 |
+| `checksum` | `string \| null` | no | max length 255 |
+| `locator` | `string \| null` | no | max length 1000 |
+| `title` | `string \| null` | no | max length 500 |