API docs by Redocly

BKN 知识网络 · 导入导出 API (1.0.0)

Download OpenAPI specification:

BKN (Business Knowledge Network) Backend API provides import and export operations for business knowledge networks.

BKN Import/Export

BKN import and export APIs

Upload and import a BKN tar archive

Upload a BKN tar archive and import it as a business knowledge network. For the archive format, see docs/design/bkn/features/bkn_docs/SPECIFICATION.md

Authorizations:
OAuth2
query Parameters
branch
string
Default: "main"

Branch name. Defaults to main.

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

Controls how environment-local bindings in the archive are imported. preserve keeps resource, Tool Box, and MCP identifiers and subjects them to proxy permission checks. detach removes those identifiers, including indirect-relation backing resources, while preserving the knowledge model topology so targets can be bound later through incremental APIs.

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: "overwrite"
Enum: "normal" "overwrite" "ignore"

Import mode. normal reports an error for duplicate concept IDs or names; overwrite updates an existing concept with the same ID; ignore skips existing concepts. A name collision with a different ID remains an error in overwrite and ignore modes. This mode controls the knowledge-network model; capability declarations in an uploaded archive are resolved and mounted independently after model processing, including when ignore leaves an existing model unchanged. Defaults to overwrite for compatibility with archive uploads that predate this parameter.

strict_mode
boolean
Default: false

Whether to require complete model definitions and validate that dependent objects exist. false permits draft definitions with optional strict-only fields omitted and skips dependency existence checks. With binding_policy=detach, true validates the archive structure before bindings are removed, but persistence dependency checks are skipped for the detached model. Defaults to false for compatibility with archive uploads that predate this parameter. When empty, the deprecated validate_dependency parameter is used.

validate_dependency
boolean
Deprecated
Default: false

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

Request Body schema: multipart/form-data
required
file
string <binary>

BKN tar archive file

Responses

Response samples

Content type
application/json
{
  • "kn_id": "string"
}

Download a BKN tar archive

Export a business knowledge network as a BKN tar archive. For the archive format, see docs/design/bkn/features/bkn_docs/SPECIFICATION.md

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Knowledge network ID

query Parameters
branch
string
Default: "main"

Branch name. Defaults to main.

bkn_spec
string
Enum: "2.0" "3.0"

Specification the archive is written in. Left out, a network with a declaration only BKN spec 3.0 can hold is written as 3.0 and every other network as 2.x, byte for byte as before. 2.0 writes 2.x and leaves 3.0 declarations out; 3.0 writes 3.0. A 3.0 export first runs the network check and is refused with BknBackend.KnowledgeNetwork.ExportNeedsNetworkCheck while it finds misplaced or invalid parameters (the error details are the check result), then reads the written package back under the 3.0 rules and is refused with BknBackend.KnowledgeNetwork.ExportNotReadableAsV3 and the reason if it does not.

Responses

Check the definitions of a knowledge network

Read-only. Reports the parameters of action types and logic properties that execution drops and a BKN spec 3.0 package refuses: misplaced ones, whose value source sits in source as the legacy parameter table (Parameter | Type | Source | Binding) wrote it, each with the rewrite the 3.0 refusal shows; and invalid ones, whose value_from is not property, input or const and which have no rewrite to suggest. Works on any network, 2.x included. It reads the definitions only, not source data.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Knowledge network ID

query Parameters
branch
string
Default: "main"

Branch name. Defaults to main.

Responses

Response samples

Content type
application/json
{
  • "misplaced_parameters": [
    ],
  • "invalid_parameters": [
    ]
}

Compare two knowledge network branches

Report what differs between two knowledge network branches, definition by definition and field by field. Both networks are named in the body: neither is the resource being addressed, and putting one in the path would suggest the comparison belongs to it.

Each side is authorized on its own, so a caller who may read one network and not the other is refused exactly as they would be asking for that network directly.

Definitions are paired by type and id. Two networks built independently share no definition ids — ids are generated per network — so their comparison degrades into "everything created, everything deleted". lineage reports that overlap up front, and fallback_by_name pairs the remainder by name when the caller opts in.

Definitions that are identical on both sides are counted in summary and left out of entries.

Authorizations:
OAuth2
Request Body schema: application/json
required
required
object (KNDiffSideRequest)
required
object (KNDiffSideRequest)
fallback_by_name
boolean
Default: false

Pair definitions by name once id matching is exhausted. A name match is a guess: two definitions can carry the same name and mean different things, so a paired entry reports both ids for a human to check, and an ambiguous name pairs with nothing.

include_unchanged
boolean
Default: false

Also return the definitions that are identical on both sides. They carry no changes — they are there to be listed, not read — and the counts in summary are the same either way. A caller that shows the whole model beside the differences asks for them; one that shows only what moved does not pay for them.

Responses

Request samples

Content type
application/json
{
  • "base": {
    },
  • "target": {
    },
  • "fallback_by_name": false,
  • "include_unchanged": false
}

Response samples

Content type
application/json
{
  • "base": {
    },
  • "target": {
    },
  • "summary": {
    },
  • "lineage": {
    },
  • "network": {
    },
  • "entries": [
    ]
}

Count the data behind one object type on each side of a comparison

Report how much data sits behind two object types: the row count of each bound resource and the number of distinct primary keys in it.

This is a separate call from the comparison because it queries the customer's own database. A comparison opens without paying for it, and pays only for the object type someone actually opens.

Two numbers is the whole of it on purpose. Per-column statistics — null rates, value distributions — cost another pass over the table for every column, and this runs while someone waits with a comparison open.

same_resource is true when both object types are bound to the same resource. The two sides are then reading one table and every number matches by construction, which is not a finding about the data. missing_keys counts rows with a NULL in any primary key column: they identify no object at all. duplicate_keys counts the rows with a complete key beyond the first for each key: a non-zero value means the resource holds rows the model believes are the same object. The two are kept apart because they are different faults, and a row without a key must not read as a duplicate.

Authorizations:
OAuth2
Request Body schema: application/json
required
required
object (ObjectDataStatsSideRequest)
required
object (ObjectDataStatsSideRequest)

Responses

Request samples

Content type
application/json
{
  • "base": {
    },
  • "target": {
    }
}

Response samples

Content type
application/json
{
  • "base": {
    },
  • "target": {
    },
  • "same_resource": true,
  • "delta": {
    }
}

BKN

Get BKN backend health and platform version

Returns BKN backend runtime information. ServerVersion is the platform version for releases in which all services share one version.

Responses

Response samples

Content type
application/json
{
  • "ServerName": "string",
  • "ServerVersion": "string",
  • "Language": "string",
  • "GoVersion": "string",
  • "GoArch": "string"
}

Batch get knowledge network names by ID

Batch return knowledge network names by ID, for example for object-level authorization pages. Missing IDs are skipped without an error. Requires application/json content type.

Authorizations:
OAuth2
Request Body schema: application/json
required
ids
Array of strings <= 100 items

List of knowledge network IDs to resolve, with at most 100 items. An empty list returns empty entries.

Responses

Request samples

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

Response samples

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

List resources

Lists resources by resource type with pagination on the unified resource platform. Currently supports resource_type=knowledge_network.

Authorizations:
OAuth2
query Parameters
resource_type
required
string
Value: "knowledge_network"

Resource type. The current implementation recognizes only knowledge_network, which represents a knowledge network. It maps to interfaces.RESOURCE_TYPE_KN.

Other values do not return an error. Instead, the default branch returns 200 with an empty response body. This is not an empty list: there is no body at all. An invalid value causes the client to fail JSON parsing or receive no data, rather than receive a 400 response.

keyword
string

Filter by name keyword. Defaults to empty.

offset
integer <int64>
Default: 0

Offset. Defaults to 0.

limit
integer <int64>
Default: 10

Page size. Defaults to 10.

sort
string
Default: "name"

Sort field. Defaults to name.

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

Sort direction. Defaults to desc.

Responses

Response samples

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