API docs by Redocly

上下文加载 · 实例子图查询 API (0.1.3)

Download OpenAPI specification:

跨对象类展开关联，两个入口按是否已知拓扑分工：

  • query_instance_subgraph：已知路径。给一条或多条「对象类 → 关系类 → 对象类 …」的路径模板，按模板批量取数，可逐节点加过滤与排序。
  • explore_subgraph：未知拓扑。只给起点对象类、方向与最大跳数，路径由引擎 散出来。「这张订单牵连到什么」这类问题走这条。

两者打的是同一个下游端点，区别只在查询模式，返回体元素同型：路径模板模式返回 entries 数组（每条路径一个子图），探索模式返回单个子图。

不要为了用 query_instance_subgraph 去先枚举关系类再拼路径——那是把探索硬凑 成取数，跳数一多就是组合爆炸，而且容易漏路径。

与 object-instance.yaml 的分工：那边是单个对象类的平面 查询，这边是跨对象类的关联展开。对象类 ID 与关系类 ID 从 schema-search.yaml 的 search_schema 或 kn-explore.yaml 的 get_kn_detail 取。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

Subgraph

按关系路径查询对象子图

relation_type_paths 可以放多条路径，每条独立查询、独立返回一个子图， 顺序与请求一致。

路径按实际走过的顺序写：

  • object_types 按节点出现顺序排列；n 跳路径长度为 n+1。即使某个节点没有 过滤条件，也必须占位保留其 id，否则顺序错位。
  • relation_types 按边出现顺序排列，长度为 n；第 i 条边连接 object_types[i] 与 object_types[i+1]，每条边只需给 relation_type_id。
  • 路径可以逆着关系类定义走。正向还是反向由服务端对照关系类定义判断：相邻 节点依次为关系类的起点、终点即正向，依次为终点、起点即反向；两者都不是则 返回 400。
  • source_object_type_id / target_object_type_id 可省略，表示本次遍历 从哪个节点走到哪个节点（即 object_types[i].id / object_types[i+1].id）， 不是关系类定义的起终点：反向遍历时两者与关系类定义相反。填写时必须与 相邻节点一致。
  • direction（forward / backward）可省略。只有关系类的起点和终点是同一 个对象类（自引用）时，相邻节点区分不出方向，默认正向；要反向走须写 backward。

路径不合法时返回 400，details 为下游错误码加说明，指出第几条边（从 1 起）、哪个关系类、路径要求的起止节点与实际填写或关系类定义的起止节点，例如 OntologyQuery.KnowledgeNetwork.InvalidParameter.TypePath: 第 2 条边 rel_order_user 与路径节点不一致：路径要求 user → order，当前填写 order → user。…。

取主键：子图对象的主键在 _instance_identity 里，与 query_object_instance 同名同义。要把子图结果喂给 action.yaml 或 logic-property.yaml 时， 从这里取键值对，不要自己拼。

Authorizations:
OAuth2AppKey
query Parameters
kn_id
required
string

知识网络 ID。

include_logic_params
boolean
Default: false

是否返回逻辑属性的计算参数。默认 false，结果不含逻辑属性字段与值。

response_format
string
Default: "json"
Enum: "json" "toon"

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

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.

required
Array of objects (RelationTypePath)

关系路径集合。多条路径同时查询，各自返回独立子图。

Responses

Request samples

Content type
application/json
Example
{
  • "relation_type_paths": [
    ]
}

Response samples

Content type
{
  • "entries": [
    ]
}

从起点探索关联子图

不需要预先知道拓扑：给起点对象类、方向与最大跳数，引擎沿概念定义的关系散开， 返回命中的对象与它们之间的路径。

分页与排序只切起点：limit / sort / offset / search_after 全部作用于 起点对象类的实例集合，不是路径条数、也不是返回对象总数。limit: 10 的含义 是「从至多 10 个起点出发」，每个起点散出多少条路径由拓扑决定。

path_length 必填，取 1-3，缺失或越界都在 Context Loader 侧返回 400。 下界必须拦在这里：path_length 为 0 时下游不报错，只返回空子图，会被读成 「什么都没连上」。路径数随跳数快速增长，先从 1-2 起步，不够再加。

condition 只过滤起点，不约束路径上的其他对象类。要约束中间节点就说明 路径其实是已知的，改用 query_instance_subgraph 逐节点加条件。

isolated_objects 是有效结论不是失败：它明确回答了「这些起点在给定方向与 跳数内没有关联」。不要因为它有值就重试或改问法。

取主键：与 query_instance_subgraph 一致，对象主键在 _instance_identity 里，可直接喂给 action.yaml 或 logic-property.yaml。

Authorizations:
OAuth2AppKey
query Parameters
kn_id
required
string

知识网络 ID。

include_logic_params
boolean
Default: false

是否返回逻辑属性的计算参数。默认 false。

response_format
string
Default: "json"
Enum: "json" "toon"

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

Request Body schema: application/json
required
source_object_type_id
required
string

探索起点的对象类 ID。

direction
required
string
Enum: "forward" "backward" "bidirectional"

探索方向。forward 沿关系定义的出边，backward 沿入边， bidirectional 两个方向都走。不确定关系怎么建模时用 bidirectional。

path_length
required
integer [ 1 .. 3 ]

最大跳数，取 1-3。超出返回 400。

object (Condition)

过滤条件。逻辑算子（and / or）用 sub_conditions 组合；叶子条件用 field + operation + value + value_from。value 与 value_from 必须成对出现，value_from 目前只支持 const。

可用算子以对象类的 condition_operations 为准，见 kn-explore.yaml。

concept_groups
Array of strings

概念分组 ID，把探索范围限定在这些分组内的概念上。不传则不限。

include_incomplete_path
boolean
Default: false

是否返回残缺路径——已走过至少一条边、但未走满 path_length 就无路可走 的那些。默认只返回完整路径。零边路径任何情况下都不返回。

limit
integer [ 1 .. 10000 ]
Default: 10

起点对象类的实例数量上限，不是路径条数上限。

Array of objects (SortSpec)

起点对象类的排序，按数组顺序依次比较。与 limit 配合决定「从哪些 起点出发」，不影响路径本身的顺序。元素不可为 null。

offset
integer

起点对象类的偏移翻页。与 search_after 互斥。

search_after
Array of any

起点对象类的游标翻页。与 offset 互斥。

Responses

Request samples

Content type
application/json
Example
{
  • "source_object_type_id": "ot_purchase_order",
  • "direction": "bidirectional",
  • "path_length": 2,
  • "condition": {
    },
  • "limit": 10
}

Response samples

Content type
{
  • "objects": {
    },
  • "isolated_objects": {
    },
  • "relation_paths": [
    ],
  • "current_path_number": 0,
  • "overall_ms": 0,
  • "total_count": 0,
  • "search_after": [
    ]
}