bk-cli-api

bk-cli api — raw API call

Directly make HTTP requests to any BlueKing API Gateway.

CRITICAL — Before starting, you MUST first use the Read tool to read ../bk-cli-shared/SKILL.md. It defines the shared rules for authentication, context, stage, timeout, header, body, tenant, dry-run, and verbose; this skill only supplements the raw request construction details unique to bk-cli api .

When to prefer this Skill

• The user already knows which gateway_nameto access, the HTTP method and path, and wants to send the request directly.
• Existing system subcommands do not yet cover the target API, but the user still wants to debug or call it through bk-cli .
• The user wants to confirm how the URL, query, path placeholder, body, or custom header will ultimately land in the request.
• The user is troubleshooting "why can't this request get through," and needs to first look at the dry-run, then the verbose output, and finally the JSON envelope.

When to look at other Skills first

• If the user does not yet know which gateways, resources, or API names exist, first look at bk-cli-apigateway for discovery and Schema browsing.
• If the issue is authentication, context, tenant, timeout, header override precedence, or other shared request rules, first look at bk-cli-shared。
• If there is already an existing system subcommand that can directly accomplish the goal, and the user does not care about the underlying URL details, prefer the system-specific skill rather than defaulting back to the raw API.

Recommended workflow

1. First use bk-cli-shared to confirm global prerequisites such as context, authentication, and stage.
2. When values can be written directly into api_path , prefer writing the values directly; only use --path。
3. when the template path is clearer. --dry-runOn the first attempt or when troubleshooting, prefer adding
4. , and after confirming the URL, headers, and body are correct, actually send it. --verboseWhen you need to see request/response details, add

; when scripts consume stdout, parse only the JSON envelope.

bk-cli api <gateway_name> <method> <api_path> [flags]

Command form	Description
gateway_name	Gateway name, for example bk-apigateway、bk-iam; must match ^[a-z][a-z0-9-]{2,29}$
method	HTTP method: GET, POST, PUT, PATCH, DELETE
api_path	API path; writing the value directly is recommended; using {placeholder} templates is also supported

Flags

Flag	Type	Description
--query	JSON string	Query parameters appended to the URL
--path	JSON string	Used to replace api_path in {placeholder} values
--body	JSON string	JSON request body; automatically sets Content-Type: application/json
--header	Repeatable	Custom request headers, in the format Key:Value, can be passed repeatedly
--stage	string	Gateway stage:prod(default) or testing
--timeout	duration	Override the current request timeout, for example 180s; by default uses the timeoutfrom context (default 60s)
--dry-run	bool	Preview the request only, do not actually execute
--context	string	Override the currently active context
--verbose	bool	Print request/response details to stderr
--insecure	bool	Skip HTTPS certificate verification, for temporary debugging only

Quick reference

# 简单 GET
bk-cli api bk-apigateway GET /api/v2/open/gateways/

# 带查询参数的 GET
bk-cli api bk-apigateway GET /api/v2/open/gateways/ \
  --query '{"name":"bk-iam","fuzzy":true}'

# 直接在路径中渲染值的 GET（推荐给 agent）
bk-cli api bk-apigateway GET /api/v2/open/gateways/bk-iam/resources/

# 通过 --path 做路径模板替换
bk-cli api bk-apigateway GET /api/v2/open/gateways/{gateway_name}/resources/ \
  --path '{"gateway_name":"bk-iam"}'

# 带请求体的 POST
bk-cli api bk-demo POST /api/v2/foo/ --body '{"name":"bar"}'

# 自定义请求头
bk-cli api bk-demo GET /api/v2/foo/ --header "X-Custom:value"

# 特殊场景下显式覆盖 auth / tenant header
bk-cli api bk-demo GET /api/v2/foo/ \
  --header 'X-Bkapi-Authorization:{"access_token":"custom-token"}' \
  --header 'X-Bk-Tenant-Id:tenant-b'

# 仅预览，不执行
bk-cli api bk-demo GET /api/v2/foo/ --dry-run

# 使用 testing stage
bk-cli api bk-demo GET /api/v2/foo/ --stage testing

# 单次请求覆盖超时
bk-cli api bk-demo GET /api/v2/foo/ --timeout 180s

Timeout

bk-cli api supports --timeout <duration> Override the context timeout for a single run; for the full precedence order, see ../bk-cli-shared/SKILL.md。

URL construction

The final URL is constructed in four steps:

1. Use gateway_name to render bk_api_url_tmpl, obtaining the base URL
2. Append /{stage}, the default is prod
3. If needed, use --path to replace the placeholders in api_path placeholder in
4. Append the resolved api_path

bk_api_url_tmpl = "https://bkapi.example.com/api/{gateway_name}/"
gateway_name    = bk-iam
stage           = prod
api_path        = /api/v2/systems/
→ https://bkapi.example.com/api/bk-iam/prod/api/v2/systems/

Path substitution

Recommended practice: If possible, write the value directly into api_path, without additionally relying on --path。

# ✅ 推荐：直接在路径里写值
bk-cli api bk-apigateway GET /api/v2/open/gateways/bk-iam/resources/

# 也支持：通过 --path 做模板替换
bk-cli api bk-apigateway GET /api/v2/open/gateways/{gateway_name}/resources/ \
  --path '{"gateway_name":"bk-iam"}'

Validation rules:

• api_path contains an unresolved {placeholder} and no --pathis provided, an error will be reported locally
• --path If the JSON is missing the key corresponding to a placeholder, an error will be reported locally
• --path contains extra keys that do not match any placeholder, an error will be reported locally
• --path is not valid JSON, an error will be reported locally
• When the placeholder name is gateway_name , its value must match ^[a-z][a-z0-9-]{2,29}$
• Path escaping, header overrides, tenant,Content-Type and masking rules, see ../bk-cli-shared/SKILL.md

Output format

Success (HTTP 2xx)

{"ok": true, "status": 200, "headers": {"X-Request-Id": "..."}, "data": {...}}

API error (HTTP non-2xx)

{"ok": false, "status": 400, "headers": {...}, "data": {...}}

CLI error (stderr)

{"ok": false, "error": {"code": "auth_required", "message": "...", "hint": "Run: bk-cli auth login"}}

Dry Run

{"ok": true, "dry_run": true, "request": {"method": "GET", "url": "...", "headers": {...}, "params": {...}, "body": null}}

Parse output

# 提取 data
bk-cli api bk-apigateway GET /api/v2/open/gateways/ | jq '.data'

# 检查是否成功
bk-cli api bk-apigateway GET /api/v2/open/gateways/ | jq '.ok'

# 获取 HTTP 状态码
bk-cli api bk-apigateway GET /api/v2/open/gateways/ | jq '.status'

Scripts read the JSON envelope on stdout by default; when troubleshooting, if you also need to see request details, combine this with the verbose output on stderr.

Common errors

Error code	Cause	Fix
config_error	Context not yet configured	bk-cli context init --bk_api_url_tmpl=...
auth_required	The current context has no credentials	bk-cli auth login
invalid_gateway_name	gateway_name input is invalid	Use a gateway name matching ^[a-z][a-z0-9-]{2,29}$ gateway name of
path_error	Placeholder unresolved, or --path JSON is invalid	Check the api_path placeholders and the value of --path value of
request_error	--query、--body or --header input is invalid	Check the JSON or header format
network_error	Request failed to send	Check network connectivity and VPN