API docs by Redocly

BKN 知识网络 · 对象类 API (0.1.0)

Download OpenAPI specification:

Object types use object_type:{kn_id}/{object_type_id}. Reads and lists require view_detail; data reads require query_data; updates and deletes use modify and delete. Lists and searches 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.

With strict_mode=true, resource-backed object types read only the Vega schema under view_detail. Main-branch publication reuses the effective delegator selected by Proxy preflight instead of requiring the current editor to repeat the downstream permission. Missing bindings return 400; a current-user permission denial returns 403; controlled lookup failures return 502, and timeout/unavailable dependencies return 503. Downstream bodies are never copied into the public response. Tool-backed logical properties use the same 400/502/503 dependency classification.

List object types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
name_pattern
string

Fuzzy-match by object type name. Empty by default.

sort
string
Enum: "update_time" "name"

Sort field. 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 returned items per page. Supported paginated values are 1 to 1000; -1 disables pagination. Defaults to 10.

tag
string

Exact-match by tag. Empty by default.

branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Create or search object types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

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, lifecycle 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" "overwrite" "ignore"

Import mode. normal returns an error for a concept with the same name; overwrite replaces it; ignore skips it. Defaults to normal.

strict_mode
boolean
Default: true

Whether to validate dependency existence. Defaults to true. When unset, falls back to the deprecated validate_dependency.

header Parameters
x-http-method-override
required
string
Enum: "POST" "GET"

Override request headers

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

Object type information

Responses

Request samples

Content type
application/json
Example
{
  • "need_total": true,
  • "limit": 1,
  • "condition": {
    }
}

Response samples

Content type
application/json
Example
{
  • "entries": [
    ],
  • "total_count": 2,
  • "next_cursor": "cursor-object-types-1"
}

Update an object type

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

ob_id
required
string

Object type ID

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. When true, validates external dependencies such as data views, embedding models, and tools used by logical properties. When false, skips this validation.

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

Name

aliases
Array of strings

Other names of the object type (BKN spec 3.0), for concept search and understanding; not its own name or another object type's name. An update that leaves the field out keeps the stored aliases; null or [] clears them.

object

Whether the object type is still in use (BKN spec 3.0, §4.3); not the index status. Without it the object type is active. status deprecated needs a reason; replaced_by names an active object type. An update that leaves the field out keeps the stored lifecycle; null or {} clears it.

tags
Array of strings

Tags used for business identification

comment
string

Comment

icon
string

Icon

color
string

Color

branch
required
string

Branch ID

Array of objects (ConceptGroup)

Concept groups

object (DataSource)

Data source

required
Array of objects (DataProperty)

Data properties

Array of objects (LogicProperty)

Logical properties

primary_keys
required
Array of strings

Primary keys that uniquely identify the object

display_key
required
string

Display property of the object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "aliases": [
    ],
  • "lifecycle": {
    },
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string",
  • "concept_groups": [
    ],
  • "data_source": {
    },
  • "data_properties": [
    ],
  • "logic_properties": [
    ],
  • "primary_keys": [
    ],
  • "display_key": "string"
}

Response samples

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

Get object type details

Authorizations:
OAuth2
path Parameters
ob_ids
required
Array of strings

Object type ID

kn_id
required
string

Business knowledge network ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Delete object types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

ob_ids
required
Array of strings

Object type ID

query Parameters
force_delete
boolean
Default: false

Whether to force deletion. Defaults to false. When false, returns an error if a relation type binds the object type; when true, deletes it without that validation.

branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Update data properties

Requires effective modify on object_type:{kn_id}/{ob_id}. Before the write, strict_mode controls request validation for vector-index embedding-model dependencies; it never bypasses authorization.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

ob_id
required
string

Object type ID

property_names
required
string

Data property name list

query Parameters
branch
string

Branch. Uses main when omitted.

strict_mode
boolean
Default: true

Whether to strictly validate the embedding model dependency for vector indexes. Defaults to true. When true and submitted data properties enable vector indexes, verifies that the model exists, has the embedding type, and has valid dimensions and parameters. When false, skips the model-service call. Request JSON index configuration validation still applies.

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

Data properties

Responses

Request samples

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

Validate object types

Validates concept dependency existence only and does not write data. Use it for pre-import checks or batch self-checks. When strict_mode is true, validates dependencies such as data views, vector-index embedding models, tools used by logical properties, and concept groups.

For same-batch references, such as a relation type referencing an object type that has not been persisted, single-type validation recognizes only persisted resources in strict mode when the request cannot include the referenced definition. In that case, use full knowledge-network validation with the same structure as the create API, or concept-group validation with nested object_types, relation_types, and action_types. The server derives BatchIDIndex from the submitted JSON, making entries visible within the same create transaction. Relation-mapping validation requires object type data properties. If a batch declares only object type IDs without property definitions, existence validation may pass while mapping-rule validation is reduced.

Response: HTTP 200 with valid set to true indicates success. Ordinary model validation failures use valid=false and detail. Strict dependency failures return the documented 400/403/502/503 error envelope, whose error_details includes a safe dependency_kind.

Internal API: POST /api/bkn-backend/in/v1/.../object-types/validation. Other behavior is the same; the caller is resolved from headers and OAuth is not required.

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, lifecycle 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"

Same as the create object type API. Defines validation semantics for persisted object type ID or name conflicts: normal, ignore, or overwrite.

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

Object type list to validate. Its structure is the same as the create API.

Responses

Request samples

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

Response samples

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

ObjectType

Get object type sample data

Returns several actual object instances for an object type to verify mappings during modeling. columns gives the display order and titles. The structure of entries elements depends on the object type property definitions, so fixed fields are not declared.

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

ot_ids
required
string

Object type ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

limit
integer
Default: 20

Number of returned entries. Defaults to 20.

offset
integer
Default: 0

Offset. Defaults to 0.

need_total
boolean
Default: true

Whether to return total_count. Defaults to true.

search_after
string

Deep-pagination cursor, separated by commas. When provided, offset is ignored.

Responses

Response samples

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