bk-cli-apigateway

bk-cli apigateway — API Gateway management

Used to discover gateways, browse gateway APIs, and obtain the OpenAPI Schema.

CRITICAL — Before starting, you MUST first use the Read tool to read ../bk-cli-shared/SKILL.md. The shared skill is responsible for general usage rules such as authentication, context, tenant, stage, header/body, dry-run, verbose, etc.; this skill only supplements the apigateway command's own discovery and invocation paths.

When to Prefer This Skill

• The user only knows "what I want to do" but does not know which public gateway or public API should be called.
• The user does not yet know which gateways are currently available, or only knows a vague name and needs to first filter, search, and browse.
• The user knows the gateway name but does not yet know the resource name, API name, or input parameters, and wants to first view the resource list and Schema.
• The user is deciding "should I use an existing apigateway subcommand here, or fall back to bk-cli api”。
• The user wants to connect API Gateway discovery results to a script or jq to continue processing.

Recommended Workflow

1. First list_gateways search for and confirm possibly related public gateways.
2. Then use list_gateway_apis to browse the gateway's public resources and narrow down to candidate APIs.
3. If the results are not unique, show the candidate gateways/APIs to the user, clearly explain why you think they are relevant, and ask the user to confirm the final target.
4. Use retrieve_gateway_api_details to view the full Schema, authentication requirements, method, path, and request/response structure.
5. If the target already has a suitable apigateway subcommand, continue using that command for discovery or viewing.
6. If you need to actually call a public API, or the target endpoint has not yet been mapped to a apigateway subcommand, switch to bk-cli api based on the protocol information in the details to make the raw call.

Agent Working Style

Discovery first, do not guess endpoints

• When the user does not know the gateway name, API name, path, or input parameters, do not directly assume the endpoint.
• First use list_gateways and list_gateway_apis to search, turning "I guess you want this endpoint" into "here are several groups of possibly matching public endpoints."
• If there are multiple candidates, first give the user a short list, then continue to the next step; do not skip the confirmation step.

How to Confirm Candidates

When giving the user candidates, try to include this information:

• gateway_name
• api_name
• A brief reason for the match, for example "the name contains system", "the description mentions permissions", "the path appears to correspond to creating an application"

The recommended wording is "I found 2 possibly related public endpoints; please confirm which one you want", rather than "I'll just call the one that looks most similar for you."

Switching from Discovery to Invocation

• bk-cli apigateway is responsible for "finding gateways, finding endpoints, viewing details, viewing Schema."
• bk-cli api is responsible for "sending requests according to the real method/path/query/body/header."
• Only after viewing the results of retrieve_gateway_api_details should you assemble the bk-cli api call, which is safer.
• For the first call, troubleshooting, or when the user is also unsure about the parameters, prefer to first generate bk-cli api ... --dry-run, confirm the URL, headers, and body before actually sending the request.

Assembling bk-cli api principles

Extract this information from the API details / Schema:

• Gateway name: corresponds to bk-cli api <gateway_name>
• HTTP method: e.g. GET、POST
• Path: fill in api_path
• query parameters: put into --query '<json>'
• path parameters: if the path template contains placeholders, use --path '<json>', otherwise write the concrete path directly
• body: put into --body '<json>'
• extra headers: only use --header

If the detail/Schema cannot uniquely explain how to call it, first tell the user the uncertain points, then confirm; do not silently fill in missing information with guessed values.

Read auth_config to do a pre-call check

retrieve_gateway_api_details If the return of

{
  "auth_config": {
    "user_verified_required": false,
    "app_verified_required": true,
    "resource_perm_required": true
  }
}

it should be understood as a precondition for calling the API, not just as a display field:

• app_verified_required: true: the caller needs to carry an app identity.
• user_verified_required: true: the caller needs to carry a user identity.
• resource_perm_required: true: in addition to having an app identity, the app usually also needs to first apply for the resource permission of that API.

For an agent, the recommended interpretation is:

• Only app_verified_required: true: first confirm that the current login ticket has an app identity, or use an access_token。
• Both app_verified_required: true and user_verified_required: true: first confirm that the current login ticket has both an app identity and a user identity, or use an access_token。
• resource_perm_required: true: even if the authentication fields are complete, it cannot be ruled out that "the app has not yet applied for that API permission".

Diagnostic hints on failure

If a subsequent bk-cli api call fails, you should combine retrieve_gateway_api_details 's auth_config to explain the error together, rather than just throwing the raw error at the user.

Prefer to give hints along the following lines:

• When the API requires app authentication but the current login method has no app identity, prompt the user to check bk_app_code / bk_app_secret, or switch to an access_token。
• When the API requires user authentication but the current login method has no user identity, prompt the user to check bk_token / bk_ticket, or switch to an access_token。
• When the API requires a resource permission and the error looks like "no permission to access / permission denied / forbidden", clearly state "this may not just be a login ticket issue; it may also be that the app has not yet applied for that API permission".
• When the API requires both an app identity and a resource permission, do not give only a single conclusion; you should tell the user to check both "whether the login identity is complete" and "whether the app has applied for the API permission".

Recommended output style:

• First explain what the API requires based on auth_config .
• Then explain whether the current error looks more like "missing identity" or "missing API permission".
• If it cannot be uniquely determined from the error alone, list the two most likely causes in order of priority; do not pretend it is a definite conclusion.

Quick start

# 1. 认证
bk-cli auth login --bk_app_code="your_app" --bk_app_secret="your_secret" --bk_token="your_token"

# 2. 列出网关
bk-cli apigateway list_gateways

# 3. 列出某个网关的 API
bk-cli apigateway list_gateway_apis --gateway_name bk-iam

# 4. 获取 API 详情 / Schema
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

Exploration flow for "uncertain APIs"

When the user gives only a business goal, for example "I want to find the public permission system APIs in BlueKing" or "I don't know which gateway to call, I just know I want to query app information", prefer to proceed in the following order:

1. Search public gateways by keyword, name, or fuzzy match.
2. Enter the most relevant one or several gateways and list the public APIs.
3. Then narrow down to candidate APIs by keyword.
4. Return the candidate interfaces to the user for confirmation.
5. Read the details/Schema for the confirmed interface.
6. Construct based on the details bk-cli api call.

Example:

# 先找可能相关的公开网关
bk-cli apigateway list_gateways --keyword "iam"
bk-cli apigateway list_gateways --name iam --fuzzy

# 再看某个网关下的公开接口
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "system"

# 确认接口后查看详情
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

Commands

list_gateways

List all API Gateways, which can be filtered by conditions.

bk-cli apigateway list_gateways [--name <name>] [--fuzzy] [--keyword <keyword>]

Flag	Type	Required	Description
--name	string	No	Gateway name filter
--fuzzy	bool	No	Enable fuzzy matching for gateway names
--keyword	string	No	Search keyword in the description field

bk-cli apigateway list_gateways --name bk-iam
bk-cli apigateway list_gateways --name iam --fuzzy
bk-cli apigateway list_gateways --keyword "identity"

list_gateway_apis

List the APIs (resources) under a certain gateway.

bk-cli apigateway list_gateway_apis --gateway_name <name> [--keyword <keyword>]

Flag	Type	Required	Description
--gateway_name	string	Yes	Gateway name, must match ^[a-z][a-z0-9-]{2,29}$
--keyword	string	No	Search keyword

bk-cli apigateway list_gateway_apis --gateway_name bk-iam
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "create"
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --header 'X-Request-Id:req-001'

retrieve_gateway_api_details

Get the complete API Schema of a certain resource, including the OpenAPI specification, request/response formats, and authentication requirements.

bk-cli apigateway retrieve_gateway_api_details --gateway_name <name> --api_name <name>

Flag	Type	Required	Description
--gateway_name	string	Yes	Gateway name, must match ^[a-z][a-z0-9-]{2,29}$
--api_name	string	Yes	API resource name

bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

query_log_by_request_id

Query API Gateway logs by request_id.

bk-cli apigateway query_log_by_request_id --request_id <id>

Flag	Type	Required	Description
--request_id	string	Yes	Request ID to query

bk-cli apigateway query_log_by_request_id --request_id=9f6563e4-cc2d-402d-b8d0-11ad26d7f6a9

Authentication and general input

Authentication,--stage、--body、--header, tenant, timeout, dry-run, verbose and other general rules see ../bk-cli-shared/SKILL.md。

Environment and request input

# 使用 testing stage，而不是 prod
bk-cli apigateway list_gateways --stage testing

# 使用不同的 context（BlueKing 部署）
bk-cli apigateway list_gateways --context clouds

# 查看实际请求/响应细节
bk-cli apigateway list_gateways --verbose

# 传入请求级 header
bk-cli apigateway list_gateway_apis --gateway_name bk-iam \
  --header 'X-Request-Id:req-001'

Description:

• --gateway_name will validate locally ^[a-z][a-z0-9-]{2,29}$, and return directly if invalid invalid_gateway_name。
• For other general request inputs and troubleshooting order, refer to ../bk-cli-shared/SKILL.md .

Raw API call

If a certain apigateway interface has not yet been mapped to a subcommand, directly use bk-cli api. For complete instructions see bk-cli-api skill。

bk-cli api bk-apigateway GET /api/v2/open/gateways/ --query '{"name":"bk-iam"}'
bk-cli api bk-apigateway GET /api/v2/open/gateways/ --dry-run

A common way to chain them is:

# 1. 发现公开网关
bk-cli apigateway list_gateways --name iam --fuzzy

# 2. 浏览该网关下的公开接口
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "system"

# 3. 查看目标接口详情 / Schema
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

# 4. 根据详情改用 bk-cli api 发真实请求
bk-cli api bk-iam POST /api/v2/systems/ --body '{"id":"demo","name":"Demo"}' --dry-run

In step 4 above, the POST, path, and body are only example forms of "building the command based on the details in step 3." When actually executing, you should rely on the protocol information returned by retrieve_gateway_api_details and do not skip confirmation and apply it directly.

Pipeline example

# 提取 data
bk-cli apigateway list_gateways | jq '.data'

# 统计某个网关的 API 数量
bk-cli apigateway list_gateway_apis --gateway_name bk-iam | jq '.data | length'

# 列出 API 名称
bk-cli apigateway list_gateway_apis --gateway_name bk-iam | jq -r '.data[].name'

apigateway The stdout of the subcommand is also a structured JSON envelope, suitable for continuing to connect to jq, shell pipeline, or other automation steps.