API docs by Redocly

BKN 知识网络 · 行动类 API (0.1.0)

Download OpenAPI specification:

Action types use action_type:{kn_id}/{action_type_id}. Reads and lists require view_detail; updates and deletes use modify and delete. execute first evaluates the concrete Action Type rule; when no direct rule exists it falls back to execute on the owning knowledge network. A direct child allow or deny takes precedence, and a deny wins when both effects exist on the same resource. 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 Tool Box and MCP binding validation uses controlled execution-factory existence lookups. A missing or unpublished binding returns 400. Permission/configuration failures, downstream 5xx responses, and invalid responses return 502; timeout or unavailable failures return 503. Raw dependency response bodies are not included in public errors.

List action types

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.

action_type
string
Enum: "add" "modify" "delete"

Query filter: filter by action category enum using the same value domain as action_type and action_intent in the response.

object_type_id
string

Bound object type

branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Create or retrieve action types

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

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

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

confirm_clear_declarations
boolean
Default: false

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

strict_mode
boolean
Default: true

Whether to strictly validate dependencies. Defaults to true. When true, validates dependencies such as bound and affected object types. When false, missing dependencies do not cause an error.

branch
string
Default: "main"

Branch. Defaults to main.

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

Request override header

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

Action type information

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

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

Update an action type

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

at_id
required
string

Action type 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 bound and affected object types and other dependencies. When false, skips validation.

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

Action type name

aliases
Array of strings

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

object

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

tags
Array of strings

Tags. May be empty.

comment
string

Comment. May be empty.

icon
string

Icon

color
string

Color

branch
required
string

Branch ID

action_type
required
string
Deprecated
Enum: "add" "modify" "delete"

Deprecated. Prefer action_intent; dual writes must agree.

action_intent
string
Enum: "add" "modify" "delete"

Recommended field stored in f_action_intent.

object_type_id
required
string <= 128 characters ^[a-z0-9][a-z0-9_-]{0,127}$

Object type ID bound to the action type

action_condition_and (object) or action_condition_or (object) or action_condition_eq (object) or action_condition_not_eq (object) or action_condition_gt (object) or action_condition_gte (object) or action_condition_lt (object) or action_condition_lte (object) or action_condition_in (object) or action_condition_not_in (object) or action_condition_range (object) or action_condition_out_range (object) or action_condition_exist (object) or action_condition_not_exist (object) (ActionCondition)
object
Deprecated

Deprecated. Use impact_contracts.

Array of objects (ImpactContractItem)

Stored in f_impact_contracts as JSON.

ToolSource (object) or MCPSource (object)

Resource bound to the action

Array of objects (Parameter)

Action resource parameters

object (Schedule)

Execution frequency configuration

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "aliases": [
    ],
  • "lifecycle": {
    },
  • "tags": [
    ],
  • "comment": "string",
  • "icon": "string",
  • "color": "string",
  • "branch": "string",
  • "action_type": "add",
  • "action_intent": "add",
  • "object_type_id": "string",
  • "condition": {
    },
  • "affect": {
    },
  • "impact_contracts": [
    ],
  • "action_source": {
    },
  • "parameters": [
    ],
  • "schedule": {
    }
}

Response samples

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

Get action type details

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

at_ids
required
Array of strings

Action type ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Delete an action type

Authorizations:
OAuth2
path Parameters
kn_id
required
string

Business knowledge network ID

at_ids
required
Array of strings

Action type ID

query Parameters
branch
string
Default: "main"

Branch. Defaults to main.

Responses

Response samples

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

Validate action types

Validates only action type dependency existence and does not persist data. It validates dependencies such as bound and affected object types.

Response: HTTP 200 uses valid and detail for ordinary model validation. 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 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.

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

Matches action type creation and validates conflicts with persisted action type IDs or names using normal, ignore, or overwrite.

confirm_clear_declarations
boolean
Default: false

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

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

Action types 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"
}