API docs by Redocly

上下文加载 · 逻辑属性求值 API (0.1.4)

Download OpenAPI specification:

批量求一批对象实例的工具型逻辑属性（tool）值。

逻辑属性不直接存在于数据源里，需要带参数计算，而参数往往藏在用户的自然语言里 （「最近一年」→ 时间窗、「按省份」→ 分析维度）。本接口先用大模型把 query 翻译成各属性的 dynamic_params，再批量取值，省掉调用方自己拼参数的工作。

对象类有哪些逻辑属性、各自需要什么参数，看 kn-explore.yaml 的 get_object_types 返回的 logic_properties[].parameters。

同一份文件里还有 POST /kn/query_metric：对象指标只支持实例集合，始终按 metric_id 与不可变的对象指标 V1 版本通过该接口取数，不绑定为逻辑属性。 已建模的指标一律不该用 run_sql 重写口径。指标清单来自 get_object_types 返回的 related_metrics。

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

LogicProperty

批量求逻辑属性值

query 的质量决定成败：参数由大模型从 query（必要时加 additional_context）里推断。查询里要含时间范围、统计维度等业务上下文， 否则会因缺参失败。

缺参返回 400，不是空结果：模型判定必需的 input 参数无法从查询推出时， 返回 400，details 里是 MISSING_INPUT_PARAMS 及逐属性的缺失说明。补上 上下文重试即可。

与之区分的是 500 DYNAMIC_PARAMS_GENERATION_FAILED：那是大模型或依赖服务 故障，不是调用方少给信息，重试或查服务状态。

结果与入参对齐：datas 与 _instance_identities 顺序一一对应，每项含 主键和本次请求的 properties。

Authorizations:
OAuth2AppKey
query Parameters
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.

kn_id
required
string

知识网络 ID。

ot_id
required
string

对象类 ID。

query
required
string

用户查询。需要包含时间范围、统计维度、业务上下文，用于生成 dynamic_params。信息不足会导致 400 缺参。

required
Array of objects

对象实例标识数组，必须从上游取，不可自拼：先调 query_object_instance 或 query_instance_subgraph，从每个对象的 _instance_identity 取值，按原顺序组成数组。

properties
required
Array of strings

要求值的工具型逻辑属性名列表（tool）。对象指标请使用 query_metric。

additional_context
string

补充上下文，如 timezone、instant、step 或对象属性，帮助模型生成更准的 dynamic_params。

llm_model
string

覆盖用于生成动态参数的大模型；留空走系统默认大模型。

object (ResolveOptions)

高级选项。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical",
  • "ot_id": "ot_company",
  • "query": "计算这些药企的经营健康度",
  • "_instance_identities": [
    ],
  • "properties": [
    ]
}

Response samples

Content type
{
  • "datas": [
    ],
  • "debug": {
    }
}

ObjectMetric

按指标口径取数

按已建模指标自身的口径计算取数，是 OT-first 指标路径的第 3 步： search_schema / get_kn_detail 锁定对象类 → get_object_types 从 related_metrics 里选定 metric_id 和 version → 本接口计算。

对象指标只支持实例集合，统一走本接口；logic-property-resolver 只负责独立的 工具型逻辑属性。指标参数由调用方显式给出，不经大模型。

version 必填，必须使用已发布、不可变的版本；query 只包含定义允许的 运行时选择（过滤条件、分析维度、毫秒时间范围）。固定口径和统计 粒度由指标定义决定，不能通过本请求覆盖。branch 指定指标所在的知识网络 分支，省略时只读取 main，不会回退到其他分支。

响应保留对象指标 V1 的 model、entries、status 和 warnings。

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

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

header Parameters
x-kn-id
string

知识网络 ID 的请求头写法；请求体里给了 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
required
string

知识网络 ID。也可用 x-kn-id 头传。

branch
string
Default: "main"

指标所属知识网络分支；省略时使用 main。

metric_id
required
string

指标 ID，取自 get_object_types 返回的 related_metrics[].id。

version
required
integer >= 1

已发布且不可变的对象指标版本，取自 related_metrics[].version。

object

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_supplychain",
  • "metric_id": "metric_product_total",
  • "version": 1
}

Response samples

Content type
{
  • "kn_id": "string",
  • "metric_id": "string",
  • "version": 0,
  • "model": { },
  • "entries": [
    ],
  • "is_approximate": true,
  • "status": "ok",
  • "empty_reason": "filtered_out",
  • "total_count": 0,
  • "next_cursor": "string",
  • "warnings": [
    ],
  • "overall_ms": 0,
  • "evaluated_at": 0,
  • "effective_window": {
    }
}