API docs by Redocly

BKN 知识网络 · 概念组 API (0.1.0)

Download OpenAPI specification:

Concept groups use concept_group:{kn_id}/{group_id}. Reads and lists require view_detail; updates use modify; deletion uses delete. Lists are 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.

Strict validation of nested object, relation, and action types preserves each child's public dependency error contract: invalid bindings remain 400, user-scoped authorization remains 403, controlled dependency failures are 502, and timeout/unavailable failures are 503.

Get concept group details

Authorizations:
OAuth2
path Parameters
kn_id
required
any
group_id
required
any
query Parameters
branch
string

Branch. Uses main when omitted.

include_statistics
boolean
Default: false

Whether to calculate and return statistics. Defaults to false.

mode
string

Response view mode. Returns the default view when empty.

Responses

Response samples

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

Update a concept group

Authorizations:
OAuth2
path Parameters
kn_id
required
any
group_id
required
any
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 object type references and other dependencies declared in the concept group. When false, skips this validation.

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

Name

tags
Array of strings

Tags used for business identification

comment
string

Comment

icon
string

Icon

color
string

Color

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

Delete one concept group

Authorizations:
OAuth2
path Parameters
kn_id
required
any
group_id
required
any
query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

List concept groups

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
name_pattern
string

Fuzzy match by 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.

branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Create a concept group

Create a concept group

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string

Branch. Uses main when omitted.

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), 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, 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.

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.

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

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

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": "string"
}

Add an object type

Requires effective modify on concept_group:{kn_id}/{group_id}. strict_mode controls dependency validation only and never bypasses authorization.

Authorizations:
OAuth2
path Parameters
kn_id
required
any
group_id
required
any
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 that object type IDs exist. When false, missing object types do not cause an error.

Request Body schema: application/json
required
required
Array of objects (AddObjectType)

Object types to add

Responses

Request samples

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

Remove an object type

Requires effective modify on concept_group:{kn_id}/{group_id}. The object types are relationship members, not independent authorization targets for this operation.

Authorizations:
OAuth2
path Parameters
kn_id
required
any
group_id
required
any
ot_ids
required
any
query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Validate concept groups

Validates only concept group dependency existence and does not persist data. It validates nested object types, relation types, action types, and their dependencies. Concept IDs in the same batch are collected from the requested concept_groups tree, including nested buckets, so strict mode can resolve references that have not yet been persisted.

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 has the same semantics, 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), 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, whose details list the declarations; pass true to clear them.

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

Matches the concept group creation API and validates conflicts with persisted concept group IDs or names using normal, ignore, or overwrite.

Request Body schema: application/json
required
entries
Array of objects

Concept groups to validate. Uses the same structure as the creation API.

Responses

Request samples

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

Response samples

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