API docs by Redocly

BKN 知识网络 · 知识网络 API (0.1.0)

Download OpenAPI specification:

Authentication requires an OAuth access token, for example the token returned by openbkn auth token after openbkn auth login. AppKeys (bak_) are not supported by these BKN management REST APIs, including read-only list and detail requests. An AppKey can be active in Safe and accepted by Context Loader while this service rejects it with HTTP 401 / Public.Unauthorized. Resource authorization is evaluated after successful authentication.

Knowledge-network CRUD uses knowledge_network:{kn_id}. Create requires knowledge_network:*:create; detail, list, update, and delete use the corresponding instance operations. Lists are authorization-filtered before total and pagination. See ../knowledge-network-authorization.md.

Resource IDs use lowercase letters, digits, underscores, and hyphens, start with a letter or digit, and contain at most 128 characters. Resource names contain at most 128 Unicode characters.

Main-branch import and overwrite perform Proxy source preflight before strict child validation. The effective delegator chosen for retained or new sources is reused for the corresponding operation-scoped dependency lookup. Nested child dependency errors keep their 400/403/502/503 status and child error code instead of being rewritten as a generic knowledge-network error.

List business knowledge networks

Authorizations:
OAuth2
query Parameters
name_pattern
string

Fuzzy match by business knowledge network name. Defaults to empty.

sort
string
Enum: "update_time" "name"

Sort type. Defaults to update_time.

direction
string
Enum: "asc" "desc"

Sort direction. Supported values are asc and desc. Defaults to desc.

offset
integer <int64>

Offset of the first returned item. Must be greater than or equal to 0. Defaults to 0.

limit
integer <int64>

Maximum number of items returned per page. Pagination accepts 1 through 1000, and -1 disables pagination. Defaults to 10.

tag
string

Exact match by tag. Defaults to empty.

Responses

Response samples

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

Create a business knowledge network

Authorizations:
OAuth2
query Parameters
confirm_clear_declarations
boolean
Default: false

With overwrite, a file that does not carry the BKN spec 3.0 declarations of an existing object type (aliases and property declarations) or action type (aliases), such as a 2.x package or an old JSON export, would clear them. Without this parameter the request is refused with 409 BknBackend.ObjectType.DeclarationsWouldBeCleared or BknBackend.ActionType.DeclarationsWouldBeCleared, whose details list the declarations; pass true to clear them.

import_mode
string
Enum: "normal" "ignore" "overwrite"

Import mode. Supported values are normal, ignore, and overwrite. Defaults to normal.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true. When true, validates dependencies such as object type and relation type views. When false, missing dependencies do not cause an error.

binding_policy
string
Default: "preserve"
Enum: "preserve" "detach"

Controls environment-local bindings in the imported model. preserve keeps resource, Tool Box, MCP, and indirect-relation backing resource identifiers and applies proxy permission checks. detach removes those identifiers while preserving model topology for later incremental binding. The request is structurally validated before detachment; persistence then skips dependency lookups for the removed environment-local bindings.

validate_dependency
boolean
Deprecated
Default: true

Deprecated. Use strict_mode instead. This parameter is retained for compatibility and is read when strict_mode is empty.

branch
string
Default: "main"

Branch. Defaults to main.

Request Body schema: application/json
required
id
string <= 128 characters ^$|^[a-z0-9][a-z0-9_-]{0,127}$

Business knowledge network ID. Immutable after creation. May contain lowercase letters, digits, underscores, and hyphens, and cannot start with an underscore or hyphen.

name
required
string <= 128 characters

Business knowledge network name

tags
Array of strings

Tags used for business identification

comment
string

Comment

icon
string

Icon

color
string

Color

branch
required
string

Branch ID

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string"
}

Response samples

Content type
application/json
{
  • "id": "example-knowledge-network-id"
}

Get business knowledge network details

Gets ontology model details and includes specification content when requested.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
mode
string
Enum: "" "export"

Query mode. Currently supports export. By default, returns only knowledge network details and not the child types, in which case detail_level has nothing to act on.

include_statistics
boolean

Whether to include statistics for concepts under the business knowledge network. Defaults to false.

branch
string
Default: "main"

Branch. Defaults to main.

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

Response detail level for the concept definitions, so it only has an effect together with mode=export. Without that mode the response carries no child types at all and the two values return the same bytes.

full returns every concept in full and is the default, kept so an existing caller sees no change.

summary trims the object types and the relation types, and nothing else. It is defined by what it removes, so anything not named here is returned as full returns it: an object type keeps its own fields, each data property loses mapped_field and condition_operations, each logic property loses data_source, parameters and analysis_dimensions, and a relation type loses mapping_rules.

Action types, metrics and risk types come back in full at either level, as do the concept groups, which on this path carry object_type_ids and statistics rather than nested concept copies.

summary is for progressively loading a large knowledge network: enough to see its shape and plan a query, without the field-level detail. Fetch that per concept from object-types/{ot_ids} and relation-types/{rt_ids}.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "kn_system_incident_event_network",
  • "name": "DIP system fault event network",
  • "tags": [
    ],
  • "comment": "DIP system fault event network",
  • "icon": "",
  • "color": "",
  • "branch": "main",
  • "creator": "a0f02238-6cec-11f0-82bb-fa1c4529a151",
  • "create_time": 1757583140948,
  • "updater": "a0f02238-6cec-11f0-82bb-fa1c4529a151",
  • "update_time": 1757583140948,
  • "detail": "Markdown text"
}

Update a business knowledge network

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true. When true, validates dependencies for nested object types, relation types, action types, and concept groups in the request. When false, skips validation.

confirm_clear_declarations
boolean
Default: false

With overwrite, a file that does not carry the BKN spec 3.0 declarations of an existing object type (aliases and property declarations) or action type (aliases), such as a 2.x package or an old JSON export, would clear them. Without this parameter the request is refused with 409 BknBackend.ObjectType.DeclarationsWouldBeCleared or BknBackend.ActionType.DeclarationsWouldBeCleared, whose details list the declarations; pass true to clear them.

import_mode
string
Default: "normal"
Enum: "normal" "overwrite" "ignore"

Import mode. normal reports an error for duplicate concept names; overwrite replaces them; ignore skips them. Defaults to normal.

Request Body schema: application/json
required
name
required
string <= 128 characters

Business knowledge network name

tags
Array of strings

Tags used for business identification

comment
string

Metric model comment

icon
string

Icon

color
string

Color

branch
required
string

Branch ID

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string"
}

Delete a business knowledge network

Deletes a business knowledge network and all of its object types, relation types, action types, and concept groups.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"
Value: "main"

Branch to delete. Only the main branch is currently supported.

Responses

Export one knowledge network for a sealed Trace projection

Internal Trace-only capability. The caller supplies a signed Ed25519 ProjectionReadGrant in X-BKN-Projection-Grant; it is not a user bearer token. BKN verifies issuer, audience, key ID, expiry, signature and that the exact path kn_id is in the grant. It never resolves user identity, tenant, business domain, a list, or a reverse lookup. A missing, invalid, expired, or non-matching grant returns 404.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

The single knowledge network explicitly authorized by the grant.

header Parameters
X-BKN-Projection-Grant
required
string

Signed ProjectionReadGrant. Do not send an Authorization bearer token.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string",
  • "skill_content": "string",
  • "creator": {
    },
  • "create_time": 0,
  • "updater": {
    },
  • "update_time": 0,
  • "statistics": {
    },
  • "concept_groups": [
    ],
  • "object_types": [
    ],
  • "relation_types": [
    ],
  • "action_types": [
    ],
  • "value_types": [
    ],
  • "module_type": "string",
  • "operations": [
    ]
}

List knowledge-network identities for authorization configuration

Internal, tokenless resource catalog for authorization configuration. It intentionally bypasses user-resource visibility filtering and returns only IDs and names from the main branch: knowledge networks by default, or the child resources of one knowledge network when resource_type names a child type. It must not be exposed through an external ingress; cluster network reachability is the access boundary.

query Parameters
resource_type
string
Enum: "knowledge_network" "object_type" "relation_type" "action_type" "concept_group" "metric"

Resource type to list. Empty or knowledge_network lists knowledge networks. The child types object_type, relation_type, action_type, concept_group and metric list the children of the knowledge network given by parent_id; any other value is rejected with 400. Child entry ids have the form "{parent_id}/{child_id}".

parent_type
string
Value: "knowledge_network"

Required for child resource types and must be knowledge_network. Ignored when listing knowledge networks.

parent_id
string

Required for child resource types. ID of the parent knowledge network. Ignored when listing knowledge networks.

name
string

Optional fuzzy match against the name of the listed resources.

sort
string
Default: "name"
Value: "name"

Only name is supported. Defaults to name.

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

Sort direction. Defaults to asc.

offset
integer >= 0
Default: 0

Offset of the first returned item. Defaults to 0.

limit
integer [ 1 .. 1000 ]
Default: 10

Maximum number of returned items. Defaults to 10.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total": 0
}

Get a bounded ontology overview graph

Returns a lightweight, authorization-filtered graph projection for large knowledge networks. Counts are calculated after authorization. The initial page and cursor pages are bounded; focus_object_type_id expands one node by one or two hops. A cursor is rejected when the network snapshot has changed. When concept_group_id is provided, counts and truncation are scoped to the visible object and relation types in that group. Concept-group cursors advance node and relation pages independently, so an edge may reference a node returned by a later page; clients should merge pages by ID before drawing the edge.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"
node_limit
integer [ 1 .. 500 ]
Default: 60

Maximum returned nodes per page. Defaults to 60; maximum 500.

edge_limit
integer [ 1 .. 1000 ]
Default: 120

Maximum candidate relations read per page. Defaults to 120; maximum 1000.

cursor
string

Opaque cursor from next_cursor. Supported for network and concept-group projections; cannot be combined with focus_object_type_id.

focus_object_type_id
string

Object type whose bounded neighbourhood should be returned.

expand_depth
integer
Default: 1
Enum: 1 2

Focus expansion depth. Supported values are 1 and 2; defaults to 1.

concept_group_id
string

Return a bounded projection of one concept group. Mutually exclusive with focus_object_type_id.

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ],
  • "object_type_total": 0,
  • "relation_type_total": 0,
  • "returned_nodes": 0,
  • "returned_edges": 0,
  • "truncated": true,
  • "snapshot": "string",
  • "next_cursor": "string"
}

Validate a business knowledge network

Validates only knowledge network dependency existence and does not persist data. It validates all dependencies including object types, relation types, action types, and concept groups. The server builds one BatchIDIndex from the four top-level request buckets and nested concept_groups buckets, allowing references to types present only in nested groups.

Response: HTTP 200 uses valid and detail for ordinary model validation. Nested strict dependency failures return the documented 400/403/502/503 error envelope, whose error_details includes a safe dependency_kind.

Internal API: the corresponding internal path uses the same request and response contract, resolves the caller from headers, and does not use OAuth.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true.

confirm_clear_declarations
boolean
Default: false

With overwrite, a file that does not carry the BKN spec 3.0 declarations of an existing object type (aliases and property declarations) or action type (aliases), such as a 2.x package or an old JSON export, would clear them. Without this parameter the request is refused with 409 BknBackend.ObjectType.DeclarationsWouldBeCleared or BknBackend.ActionType.DeclarationsWouldBeCleared, whose details list the declarations; pass true to clear them.

import_mode
string
Default: "normal"
Enum: "normal" "ignore" "overwrite"

Matches creation semantics. When neither import_mode nor mode is provided, uses normal. It validates persisted ID and name conflicts with normal, ignore, and overwrite semantics.

Request Body schema: application/json
required
object_types
Array of arrays
relation_types
Array of arrays
action_types
Array of arrays
concept_groups
Array of arrays
value_types
Array of arrays

Responses

Request samples

Content type
application/json
{
  • "object_types": [ ],
  • "relation_types": [ ],
  • "action_types": [ ],
  • "concept_groups": [ ],
  • "value_types": [ ]
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "detail": "string"
}