/volcengine-api

name: volcengine-api
description: >
  Query and answer questions about Volcengine API specifications. Trigger this skill whenever a user
  asks about Volcengine API parameters, error codes, request methods, enum values, required fields,
  response structures, pagination, parameter dependencies, or API comparisons — even if they don't
  explicitly say "API". Typical triggers include questions like "What parameters does DescribeInstances
  have?", "What values does Status support?", "What does InvalidInstanceId.NotFound mean?",
  "Does Volcengine have a batch tag deletion API?", "Which APIs does ECS support?",
  "How do I pass parameters to CreateDatabase?", "Is ChargeType required?",
  "What fields does DescribeInstances return?", "How do I paginate instance lists?",
  "What's the difference between these two APIs?", "RunInstances returns InvalidParameterValue".
  When the user needs runnable SDK code, hand off to the volcengine-sdk-generator skill.
  When the user needs CLI-based operations, hand off to the volcengine-cli skill.
  Supports both Chinese and English prompts.

Volcengine API Query Assistant

Answer user questions about Volcengine APIs by querying the API Explorer for authoritative, up-to-date information.

Applicable Scenarios

| Scenario | Example Questions | |----------|-------------------| | Find an API | "How do I list ECS instances?", "Is there a batch tag creation API?" | | Query parameters | "What are the required params for RunInstances?", "What values does ChargeType accept?" | | Response structure | "What fields does DescribeInstances return?", "What statuses can Status have?" | | Parameter dependencies | "If I set Ipv6Isp, how should I fill Ipv6MaskLen?", "When is SpotPriceLimit required?" | | Pagination | "How do I paginate instance queries?", "How does NextToken work?" | | Error codes | "What does InvalidInstanceId.NotFound mean?", "CreateVpc returns QuotaExceeded" | | Browse services | "Which APIs does ECS have?", "What operations does VPC support?" | | API comparison | "What's the difference between DescribeInstances and DescribeInstancesByIds?" |

Workflow

Step 1: Understand User Intent

Determine what the user is looking for:

| Intent | Signal | Query Path | |--------|--------|------------| | **Find an API** | Describes an operation but doesn't know the API name | Search (2e) or Services (2a) -> API list (2c) -> Details (2d) | | **Query parameters** | Knows the API name, asks about params/enums/required fields | Go directly to Details (2d) | | **Query response** | Asks about return fields or status values | Go directly to Details (2d), focus on response schema | | **Query parameter dependencies** | Asks "when is X required?" or "how does X relate to Y?" | Go directly to Details (2d), focus on conditional rules in descriptions | | **Query error codes** | Provides an error code or error message | Error code handling (Step 3) | | **Browse a service** | Asks what capabilities a service offers | Services (2a) -> API list (2c) | | **Compare APIs** | Asks about differences between two APIs | Query Details (2d) for each, compare params and functionality |

Step 2: Query API Information Progressively

Start from the appropriate sub-step based on what is already known. When the user describes a requirement in natural language, Search (2e) is often faster than browsing level by level.

2a. Query service list (when the service is unknown)

GET https://api.volcengine.com/api/common/explorer/services

Each service in the response contains:

• `ServiceCode`: service identifier (e.g., `ecs`, `vpc`)
• `ServiceCn`: Chinese name (e.g., "cloud server", "virtual private cloud")
• `Product`: product identifier (e.g., `ECS`, `VPC`)
• `RegionType`: `regional` or `global`

Match the most appropriate `ServiceCode` based on the user's description.

2b. Query version list (when the version is unknown)

GET https://api.volcengine.com/api/common/explorer/versions?ServiceCode={ServiceCode}

Each version contains:

• `Version`: version string (e.g., `2020-04-01`)
• `IsDefault`: `1` indicates the default version

Prefer the version with `IsDefault=1`. If none is marked default, use the latest version.

2c. Query API list (when the specific API is unknown)

GET https://api.volcengine.com/api/common/explorer/apis?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}

The response groups APIs by category. Each API contains:

• `Action`: API name (e.g., `DescribeInstances`)
• `NameCn`: Chinese name (e.g., "Query instance list")
• `ApiGroup`: group name (e.g., "Instance", "Image")
• `Description`: functional description
• `UsageScenario`: usage scenarios
• `Attentions`: constraints and caveats

Match user intent using `Action`, `NameCn`, and `Description`.

2d. Query API details (core step)

GET https://api.volcengine.com/api/common/explorer/api-swagger?ServiceCode={ServiceCode}&Version={Version}&APIVersion={Version}&ActionName={ActionName}

Returns the full Swagger/OpenAPI specification for the API. Extract key information as follows.

HTTP Method

The key under `paths["/{ActionName}"]` (`get` or `post`) indicates the HTTP method.

Request Parameters

Parameter location depends on the HTTP method:

**GET requests:** parameters are in `paths["/{ActionName}"].get.parameters`. Each parameter includes:

• `name`: parameter name
• `required`: whether it is required
• `schema.type`: data type
• `schema.description`: parameter description (often contains enum values, conditional rules, and value ranges)
• `schema.enum`: allowed values (if any)
• `schema.default`: default value (if any)
• `schema.example`: example value (if any)

Arrays and nested objects in GET parameters use naming conventions:

• Arrays: `ParamName.N` (N starts from 1), e.g., `InstanceIds.1`, `InstanceIds.2`
• Nested objects: `Parent.Child`, e.g., `TagFilters.N.Key`, `TagFilters.N.Values.N`

**POST requests:** parameters are in `paths["/