API docs by Redocly

上下文加载 · 知识网络浏览 API (0.1.3)

Download OpenAPI specification:

Context Loader（服务名 agent-retrieval）的知识网络浏览接口：从「有哪些知识网络」 到「这张网里有哪些对象类 / 关系类」，再按需下钻取完整定义。

与 schema-search.yaml 的分工：search_schema 是语义入口 （给一句话，猜相关概念）；本文件是确定性入口（列全量、按 ID 精确取）。

渐进式披露：get_kn_detail 默认 detail_level=summary，只返回骨架加属性名， 把属性的字段映射、可用算子、关系映射规则等重货剥掉——一张中等规模的网，summary 比 full 少四分之一以上的 token。需要这些细节时，再用 get_object_types / get_relation_types 按 ID 批量下钻。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ 前缀的 AppKey）。所有端点均为 POST，无请求体的也走 POST。

KnExplore

列出知识网络

列出当前账户可见的知识网络，用于发现 kn_id。请求体可选；不传按默认分页 （limit=20，按更新时间倒序）返回。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
optional
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

name_pattern
string

按名称模糊过滤。

limit
integer
Default: 20

单页数量。

offset
integer

偏移，用于翻页。

sort
string
Default: "update_time"

排序字段。

direction
string
Default: "desc"
Enum: "asc" "desc"

排序方向。

Responses

Request samples

Content type
application/json
{
  • "name_pattern": "医药",
  • "limit": 10
}

Response samples

Content type
{
  • "entries": [
    ],
  • "total_count": 0
}

获取知识网络详情

返回一张知识网络的概念全景：概念组、对象类、关系类、行动类。

detail_level 决定返回多少：

级别 保留 剥掉
summary（默认） 骨架 + 每个属性的 name / type 属性的 display_name / comment / mapped_field / condition_operations，逻辑属性的 data_source / parameters，关系类的 mapping_rules 与起终点对象类详情
full 全部 ——

两种级别都会去掉 concept_groups 里嵌套的对象类 / 关系类 / 行动类副本： 这些是顶层数组的重复拷贝，概念组只保留 object_type_ids 作为分组边界。

两种级别都不带 BKN 3.0 声明，这些只由 search_schema 给出：对象类、关系类、 行动类的 aliases；对象类属性和间接关系 mapping_rules.properties 中关系属性的 aliases / semantic / required / constraints；关系类的 reverse_name / cardinality / constraints / verification。关系类的 lifecycle、importance、 fallback_for 保留：它们说明弃用的关系由谁替代、哪条是替代路径，缺了调用方可能把 主关系和替代路径的结果相加。

被剥掉的细节按需用 get_object_types / get_relation_types 取回。 对象类条目带 related_metric_count（该对象类下已建模指标数），>0 才值得 为取指标下钻。

顶层带 mounted_capabilities：该网络已挂载的 Skill 与工具按类型计数。两个 detail_level 都会返回——它是网络的形状，不是可以剥掉的细节。同样只给计数： 要具体能力用 search_capabilities。

超过 200 个对象类、或超过 600 个关系类的网络只返回导航壳，两个 detail_level 都是：此时 object_types / relation_types / action_types **均回 null**，改由 object_type_count / relation_type_count / action_type_count 给出数量， notice 说明原因与下一步。概念组与 mounted_capabilities 照常返回。

该网络没划概念组时（存在这种网：一千个对象类、零个概念组），concept_groups 为空，notice 改为让调用方直接调 search_schema 按语义召回——把人指向一个空字段 等于没给出路。

这不是分页。一张一千对象类的网，summary 也有一兆多，翻页只是把同样的体积分几次 搬运；而按名称序翻页等于对知识模型做线性扫描。该规模下的路径是：从 concept_groups 选出 1-3 个相关分组，用 schema-search.yaml 的 search_schema 配合 search_scope.concept_groups 收敛，再用 get_object_types 按 ID 取细节。

非 main 分支暂不支持通过 search_schema 召回概念。此时用相同 branch 调 get_object_types，不传 ids 按页列举对象类索引，再带选中的 ids 读取完整定义和关联指标。

收窄发生在逐对象类的属性授权读取之前：那一步每个对象类一次下游调用，为一份 不会返回的列表付这个代价没有意义。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
optional
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

branch
string
Default: "main"

知识网络分支；省略时使用 main。

detail_level
string
Default: "summary"
Enum: "summary" "full"

详情级别，见端点说明。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical"
}

Response samples

Content type
{
  • "id": "string",
  • "name": "string",
  • "comment": "string",
  • "concept_groups": [
    ],
  • "object_types": [
    ],
  • "relation_types": [
    ],
  • "action_types": [
    ],
  • "mounted_capabilities": {
    },
  • "object_type_count": 0,
  • "relation_type_count": 0,
  • "action_type_count": 0,
  • "notice": "string"
}

按 ID 批量取对象类完整定义

取 get_kn_detail 在 summary 级别剥掉的对象类细节：属性的 mapped_field （写 run_sql 要的物理列名）、condition_operations（该属性可用的查询算子）、 逻辑属性的 data_source 与 parameters。与 get_kn_detail 相同，不带对象类与属性的 BKN 3.0 声明（aliases / semantic / required / constraints），用 search_schema 取。

同时返回 related_metrics——挂在该对象类下的已发布实例集合指标。这是 Agent 选指标的权威清单，选定后统一走 query_metric。logic_properties 只包含工具型 逻辑属性，通过 logic-property.yaml 的 logic-property-resolver 按对象实例求值；二者不建立绑定关系。

ids 里既可以传对象类 ID，也可以传对象类名（ID 优先，名称仅作兜底）； 匹配不到的 ID 原样回填在 missing 里，不报错。属性的 display_name （纯 UI 标签）在本接口也会被去掉。

不传 ids 就是列举对象类索引：按名称升序返回一页，每条只有 id / name / comment / tags / data_source，**没有 data_properties、 logic_properties 与 related_metrics**。limit 默认 50、上限 200，响应带 total_count（当前账号可见总数）与 next_offset（走完最后一页即不再出现， 别自己用 offset + len 推）。

这是给拿不到 ID 的调用方准备的——get_kn_detail 对超过上限的网络只回导航壳， 那条路给不出 ID。挑好之后把 ID 传回本接口取完整定义。传了 ids 则 offset / limit 无效。

索引而非定义，是因为完整定义在大网络上一条约 60KB：一页 20 条就超过一兆， 正是导航壳要避免的那种返回值；而且每条还要付一次属性级授权读取。索引条目 只有几百字节，且一次下游读取就能取回整页。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
required
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

branch
string
Default: "main"

对象类与关联指标所属的知识网络分支；省略时使用 main。

ids
Array of strings

要下钻的对象类 ID 列表（取自 get_kn_detail 或本接口的列举模式）。也接受 名称作为兜底匹配。留空即切换到列举模式，不再返回 400。

offset
integer >= 0
Default: 0

列举的起始位置。仅在不传 ids 时有效；续页请用响应里的 next_offset。

limit
integer [ 1 .. 200 ]
Default: 50

列举的单页条数，默认 50、上限 200。仅在不传 ids 时有效。索引条目只有 几百字节，所以比按 ID 取定义时能装得多。超过上限不报错，按上限返回， 并在响应的 notice 里说明——一页比你要的短却什么都不说，会被读成 「这张网就这么大」。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical",
  • "ids": [
    ]
}

Response samples

Content type
{
  • "kn_id": "string",
  • "object_types": [
    ],
  • "missing": [
    ],
  • "total_count": 0,
  • "next_offset": 0,
  • "notice": "string"
}

按 ID 批量取关系类完整定义

get_object_types 的关系类版本：取回 summary 级别剥掉的 mapping_rules 与起终点对象类详情。同样支持按名称兜底匹配，未命中的 ID 落 missing。

与 get_kn_detail 相同，不带 BKN 3.0 声明：关系类的 aliases / reverse_name / cardinality / constraints / verification，以及间接关系 mapping_rules.properties 中关系属性的 aliases / semantic / required / constraints，用 search_schema 取。 关系属性的 name / display_name / type / comment / mapped_field 照常返回； lifecycle、importance、fallback_for 保留。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
required
object (BKNContext)

BKN Trace business-provenance context identifying the business conversation and interaction to which this call belongs. Required on MCP business tools and REST execution APIs while capture is enabled and Trace Core is available; optional on REST reads and /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded.

Both required child fields are server-issued handles and must not be invented by the caller:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

ids
required
Array of strings

要下钻的概念 ID 列表（取自 get_kn_detail）。也接受概念名称作为兜底匹配。 为空时返回 400。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_medical",
  • "ids": [
    ]
}

Response samples

Content type
{
  • "kn_id": "string",
  • "relation_types": [
    ],
  • "missing": [
    ]
}