volcengine-api

What this skill does

# 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["/{ActionName}"].post.requestBody.content["application/json"].schema`, using JSON Schema:
- `properties`: parameter definitions, keyed by name
- `required`: array of required parameter names

POST parameters often have nested structures that require recursive parsing:
- `type: object` -> inspect `properties` for child parameters
- `type: array` -> inspect `items` for element structure
- `$ref: "#/components/schemas/XxxObject"` -> look up the definition in `components.schemas` and expand recursively

Present nested parameters in a tree structure:
```
- InstanceId (string, required): instance ID
- DatabasePrivileges (array, optional): database privilege list
  - AccountName (string, required): account name
  - AccountPrivilege (string, required): privilege type — enum: ReadWrite, ReadOnly, ...
  - AccountPrivilegeDetail (string, optional): privilege detail, comma-separated
```

##### Parameter Dependencies

Many parameters have conditional dependencies, typically described in the `description` field. Watch for:

- **Conditionally required**: e.g., "required when `EnableIpv6` is true"
- **Mutually exclusive**: e.g., "when `Ipv6CidrBlock` is specified, `Ipv6MaskLen` is ignored"
- **Value constraints**: e.g., "when `Ipv6Isp` is BGP, only 56 is supported"
- **Prerequisites**: e.g., "`TagFilters.N.Values.N` requires `TagFilters.N.Key` to be set first"

Highlight these dependencies in the answer to help users avoid misconfiguration.

##### Pagination Parameters

Volcengine APIs use two common pagination patterns, identifiable from the Swagger parameters:

- **Token-based**: uses `MaxResults` (page size) + `NextToken` (continuation token). The response includes `NextToken`; an empty value means the last page.
- **Offset-based**: uses `PageSize` + `PageNumber` (or `Offset`/`Limit`). The response includes `TotalCount`.

Specify which pagination pattern the API uses, along with default values and upper limits.

##### Response Structure

The response schema is defined at `paths["/{ActionName}"].{method}.responses["200"].content["application/json"].schema`, and may reference `components.schemas` via `$ref`.

Key response information:
- Field names, types, and descriptions
- Enum fields and their possible values (e.g., `Status`: RUNNING / STOPPED / CREATING)
- Nested object structures (e.g., fields within each item in an `Instances` array)

The `info.x-demo` section also provides useful reference — `responseDemo[0].Code` shows the complete response structure with example values.

##### Request/Response Examples

In the `info.x-demo` array:
- `requestDemo[0].Code`: request example (shows how parameters are filled)
- `responseDemo[0].Code`: response example (shows the full return structure with sample values)

These are official examples and highly valuable. Proactively include them in the answer.

##### Associated Error Codes

In `paths["/{ActionName}"].{method}.responses["x-error-code"].content["application/json"].schema.oneOf`, each error code contains:
- `code`: error code identifier (e.g., `InvalidInstanceId.NotFound`)
- `http_code`: HTTP status code (e.g.