⚙️ 开发运维

http-api

提供通过标准 HTTP 协议调用 CloudBase 平台各项能力的通用接入方式，覆盖数据库操作、云函数调用、云存储管理、AI 服务及用户认证等场景，适用于无 SDK 环境的后端服务、脚本集成与自动化测试。

快捷安装

在终端运行此命令，即可一键安装该 Skill 到您的 Claude 中

npx skills add TencentCloudBase/CloudBase-MCP --skill "http-api"

Standalone Install Note

If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.

  • CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
  • Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/http-api/SKILL.md

Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.

Activation Contract

Use this first when

  • The request comes from Android, iOS, Flutter, React Native, non-Node backends, or admin scripts that must call official CloudBase APIs via raw HTTP.
  • The task is to consume CloudBase platform endpoints, not to build a new HTTP service on CloudBase.

Read before writing code if

  • The platform does not support a CloudBase SDK, or the user explicitly asks for HTTP API integration.
  • The user says “HTTP API” but it is unclear whether they mean official CloudBase endpoints or their own business API.

Then also read

  • Auth configuration -> ../auth-tool/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md)
  • MySQL MCP management -> ../relational-database-tool/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/relational-database-tool/SKILL.md)
  • Your own HTTP service on CloudBase -> ../cloud-functions/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md) or ../cloudrun-development/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudrun-development/SKILL.md)

Do NOT use for

  • CloudBase Web SDK flows, mini program SDK flows, or MCP-driven management tasks.
  • Building your own HTTP service or REST API on CloudBase.

Common mistakes / gotchas

  • Treating Web SDK examples as valid for native Apps.
  • Guessing endpoints without reading OpenAPI definitions.
  • Confusing official CloudBase HTTP APIs with your own function or CloudRun endpoint.
  • Mixing raw HTTP API integration with MCP management logic.

Minimal checklist

When to use this skill

Use this skill whenever you need to call CloudBase platform features via raw HTTP APIs, for example:

  • Non-Node backends (Go, Python, Java, PHP, etc.)
  • Integration tests or admin scripts that use curl or language HTTP clients
  • Direct database operations via 关系型数据库 RESTful API (MySQL/PostgreSQL)
  • Cloud function invocation via HTTP
  • Any scenario where SDKs are not available or not preferred

Do not use this skill for:

  • Frontend Web apps using @cloudbase/js-sdk (use CloudBase Web skills)
  • Node.js code using @cloudbase/node-sdk (use CloudBase Node skills)
  • Authentication flows (use CloudBase Auth HTTP API skill for auth-specific endpoints)

How to use this skill (for a coding agent)

  1. Clarify the scenario

    • Confirm this code will call HTTP endpoints directly (not SDKs).
    • Ask for:
      • env – CloudBase environment ID
      • Authentication method (AccessToken, API Key, or Publishable Key)
    • Confirm which CloudBase feature is needed (database, functions, storage, etc.).
    • For user authentication: If no specific method is requested, always default to Phone SMS Verification - it’s the most user-friendly and secure option for Chinese users.

  2. Determine the base URL

    • Use the correct domain based on region (domestic vs. international).
    • Default is domestic Shanghai region.

  3. Set up authentication

    • Choose appropriate authentication method based on use case.
    • Add Authorization: Bearer <token> header to requests.

  4. Reference OpenAPI Swagger documentation

    • MUST use searchKnowledgeBase tool to get OpenAPI specifications
    • Use the tool with mode=openapi and specify the apiName:
      • mysqldb - 关系型数据库 RESTful API (MySQL/PostgreSQL)
      • nosql - NoSQL RESTful API (文档型数据库)
      • functions - Cloud Functions API
      • auth - Authentication API
      • cloudrun - CloudRun API
      • storage - Storage API
      • ai_model - AI 大模型接入 API
    • Example: searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" })
    • Parse the returned YAML content to understand exact endpoint paths, parameters, request/response schemas
    • Never invent endpoints or parameters - always reference the swagger documentation

Overview

CloudBase HTTP API is a set of interfaces for accessing CloudBase platform features via HTTP protocol, supporting database, user authentication, cloud functions, cloud hosting, cloud storage, AI, and more.

OpenAPI Swagger Documentation

⚠️ IMPORTANT: Always use searchKnowledgeBase tool to get OpenAPI Swagger specifications

Before implementing any HTTP API calls, you should:

  1. Use searchKnowledgeBase tool to get OpenAPI documentation:

    searchKnowledgeBase({ mode: "openapi", apiName: "<api-name>" })

  2. Available API names:

    • mysqldb - 关系型数据库 RESTful API (MySQL/PostgreSQL)
    • nosql - NoSQL RESTful API (文档型数据库)
    • functions - Cloud Functions API
    • auth - Authentication API
    • cloudrun - CloudRun API
    • storage - Storage API
    • ai_model - AI 大模型接入 API

  3. Parse and use the swagger documentation:

    • Extract exact endpoint paths and HTTP methods
    • Understand required and optional parameters
    • Review request/response schemas
    • Check authentication requirements
    • Verify error response formats

  4. Never invent API endpoints or parameters - always base your implementation on the official swagger documentation.

Prerequisites

Before starting, ensure you have:

  1. CloudBase environment created and activated
  2. Authentication credentials (AccessToken, API Key, or Publishable Key)

Authentication and Authorization

CloudBase HTTP API requires authentication. Choose the appropriate method based on your use case:

AccessToken Authentication

Applicable environments: Client/Server
User permissions: Logged-in user permissions

How to get: Use searchKnowledgeBase({ mode: "openapi", apiName: "auth" }) to get the Authentication API specification

API Key

Applicable environments: Server
User permissions: Administrator permissions

⚠️ Warning: Tokens are critical credentials for identity authentication. Keep them secure. API Key must NOT be used in client-side code.

Publishable Key

Applicable environments: Client/Server
User permissions: Anonymous user permissions

💡 Note: Can be exposed in browsers, used for requesting publicly accessible resources, effectively reducing MAU.

API Endpoint URLs

CloudBase HTTP API uses unified domain names for API calls. The domain varies based on the environment’s region.

Domestic Regions

For environments in domestic regions like Shanghai (ap-shanghai), use:

https://{your-env}.api.tcloudbasegateway.com

Replace {your-env} with the actual environment ID. For example, if environment ID is cloud1-abc:

https://cloud1-abc.api.tcloudbasegateway.com

International Regions

For environments in international regions like Singapore (ap-singapore), use:

https://{your-env}.api.intl.tcloudbasegateway.com

Replace {your-env} with the actual environment ID. For example, if environment ID is cloud1-abc:

https://cloud1-abc.api.intl.tcloudbasegateway.com

Using Authentication in Requests

Add the token to the request header:

Authorization: Bearer <access_token/apikey/publishable_key>

:::warning Note

When making actual calls, replace the entire part including angle brackets (< >) with your obtained key. For example, if the obtained key is eymykey, fill it as:

Authorization: Bearer eymykey

:::

Usage Examples

Cloud Function Invocation Example

curl -X POST "https://your-env-id.api.tcloudbasegateway.com/v1/functions/YOUR_FUNCTION_NAME" \
  -H "Authorization: Bearer <access_token/apikey/publishable_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "age": 25}'

For detailed API specifications, always download and reference the OpenAPI Swagger files mentioned above.

关系型数据库 RESTful API (PostgREST 风格)

适用于 MySQL 和 PostgreSQL：两者均基于 PostgREST 风格暴露 REST API，端点格式和请求语义一致。

提供关系型数据库（MySQL / PostgreSQL）的 HTTP 操作接口。

Base URL Patterns

Support three domain access patterns:

  1. https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{table}
  2. https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{schema}/{table}
  3. https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{instance}/{schema}/{table}

Where:

  • envId is the environment ID
  • instance is the database instance identifier
  • schema is the database name
  • table is the table name

If using the system database, recommend pattern 1.

Request Headers

HeaderParameterDescriptionExample
Acceptapplication/json, application/vnd.pgrst.object+jsonControl data return formatAccept: application/json
Content-Typeapplication/json, application/vnd.pgrst.object+jsonRequest content typeContent-Type: application/json
PreferOperation-dependent feature values- return=representation Write operation, return data body and headers
- return=minimal Write operation, return headers only (default)
- count=exact Read operation, specify count
- resolution=merge-duplicates Upsert operation, merge conflicts
- resolution=ignore-duplicates Upsert operation, ignore conflicts		Prefer: return=representation
AuthorizationBearer <token>Authentication tokenAuthorization: Bearer <access_token>

Query Records

GET /v1/rdb/rest/{table}

Query Parameters:

  • select: Field selection, supports * or field list, supports join queries like class_id(grade,class_number)
  • limit: Limit return count
  • offset: Offset for pagination
  • order: Sort field, format field.asc or field.desc

Example:

# Before URL encoding
curl -X GET 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?select=name,position&name=like.%张三%&title=eq.文章标题' \
  -H "Authorization: Bearer <access_token>"

# After URL encoding
curl -X GET 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?select=name,position&name=like.%%E5%BC%A0%E4%B8%89%&title=eq.%E6%96%87%E7%AB%A0%E6%A0%87%E9%A2%98' \
  -H "Authorization: Bearer <access_token>"

Response Headers:

  • Content-Range: Data range, e.g., 0-9/100 (0=start, 9=end, 100=total)

Insert Records

POST /v1/rdb/rest/{table}

Request Body: JSON object or array of objects

💡 Note about _openid: When a user is logged in (using AccessToken authentication), the _openid field is automatically populated by the server with the current user’s identity. You do NOT need to manually set this field in INSERT operations - the server will fill it automatically based on the authenticated user’s session.

Example:

curl -X POST 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course' \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "name": "数学",
    "position": 1
  }'

Update Records

PATCH /v1/rdb/rest/{table}

Request Body: JSON object with fields to update

Example:

curl -X PATCH 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?id=eq.1' \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "name": "高等数学",
    "position": 2
  }'

⚠️ Important: UPDATE requires a WHERE clause. Use query parameters like ?id=eq.1 to specify conditions.

Delete Records

DELETE /v1/rdb/rest/{table}

Example:

curl -X DELETE 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?id=eq.1' \
  -H "Authorization: Bearer <access_token>"

⚠️ Important: DELETE requires a WHERE clause. Use query parameters to specify conditions.

Error Codes and HTTP Status Codes

Error CodeHTTP StatusDescription
INVALID_PARAM400Invalid request parameters
INVALID_REQUEST400Invalid request content: missing permission fields, SQL execution errors, etc.
INVALID_REQUEST406Does not meet single record return constraint
PERMISSION_DENIED401, 403Authentication failed: 401 for identity authentication failure, 403 for authorization failure
RESOURCE_NOT_FOUND404Database instance or table not found
SYS_ERR500Internal system error
OPERATION_FAILED503Failed to establish database connection
RESOURCE_UNAVAILABLE503Database unavailable due to certain reasons

Response Format

  1. All POST, PATCH, DELETE operations: Request header with Prefer: return=representation means there is a response body, without it means only response headers.

  2. POST, PATCH, DELETE response bodies are usually JSON array type []. If request header specifies Accept: application/vnd.pgrst.object+json, it will return JSON object type {}.

  3. If Accept: application/vnd.pgrst.object+json is specified but data quantity is greater than 1, an error will be returned.

URL Encoding

When making requests, please perform URL encoding. For example:

Original request:

curl -i -X GET 'https://{{host}}/v1/rdb/rest/course?select=name,position&name=like.%张三%&title=eq.文章标题'

Encoded request:

curl -i -X GET 'https://{{host}}/v1/rdb/rest/course?select=name,position&name=like.%%E5%BC%A0%E4%B8%89%&title=eq.%E6%96%87%E7%AB%A0%E6%A0%87%E9%A2%98'

NoSQL RESTful API

NoSQL RESTful API 提供文档型数据库（NoSQL）的 HTTP 操作接口，支持集合管理、文档 CRUD、聚合查询、事务操作和数据库命令。

Base URL

https://{envId}.api.tcloudbasegateway.com/v1/database/instances/{instance}/databases/{database}/
参数说明
envId环境 ID
instance数据库实例 ID，默认实例使用 (default)
database数据库名称，默认数据库使用 (default)

示例：

  • 默认实例 + 默认数据库：/v1/database/instances/(default)/databases/(default)/
  • 指定实例 + 默认数据库：/v1/database/instances/test_instance/databases/(default)/

请求与响应格式

  • 请求支持 Relaxed 和 Strict EJSON 格式
  • 响应均为 Strict EJSON 格式
  • EJSON 支持的特殊类型：ObjectId、Date、Int、Long、Decimal128、Binary、RegExp

错误码与 HTTP 状态码

错误码HTTP 状态码说明
INVALID_PARAM400参数错误
DATABASE_PERMISSION_DENIED401权限不足
DATABASE_INVALID_OPERRATOR403不支持的操作
DATABASE_COLLECTION_NOT_EXIST404集合不存在
DOCUMENT_NOT_FOUND404文档不存在
DATABASE_COLLECTION_ALREADY_EXIST409集合已存在
DATABASE_DUPLICATE_WRITE409唯一索引冲突
EXCEED_REQUEST_LIMIT422请求次数超限
EXCEED_CONCURRENT_REQUEST_LIMIT422并发请求超限
DATABASE_REQUEST_FAILED500数据库请求失败
SYS_ERR500内部错误
DATABASE_TRANSACTION_CONFLICT503事务冲突
DATABASE_TRANSACTION_FAIL503事务执行失败
DATABASE_TIMEOUT504数据库操作超时

详细端点使用和请求示例，请参考官方文档：https://docs.cloudbase.net/http-api/nosql/nosql-restful-api

AI 大模型接入 API

统一的大模型接入 API，支持通过 HTTP 调用已配置的 AI 大模型（支持 SSE 流式响应）。

认证方式

方式说明
Authorization: Bearer <token>AccessToken 认证（推荐）
TC3-HMAC-SHA256 签名腾讯云 API v3 签名方式
Authorization: <apikey>APIKey 认证

AccessToken 获取方式：参考 Auth OpenAPI (searchKnowledgeBase({ mode: "openapi", apiName: "auth" }))

错误码

错误码说明
AI_MODEL_CONFIG_MISSING缺少模型 API Key 或配置
AI_MODEL_PARAM_INVALID输入参数无效
AI_MODEL_DISABLED模型已禁用，请在控制台检查或等待约 2 分钟
AI_MODEL_NOT_SUPPORTED请求模型不支持或未启用
AI_MODEL_PARAM_REQUIRED缺少必需参数 model
AI_MODEL_NOT_FOUND指定的模型组不存在
EXCEED_CONCURRENT_REQUEST_LIMIT并发请求超限，请稍后重试或申请更高配额
EXCEED_TOKEN_QUOTA_LIMIT模型 Token 配额超限，请购买资源或调整模型组

详细端点和请求格式，请参考官方文档：https://docs.cloudbase.net/http-api/ai-model/ai-%E5%A4%A7%E6%A8%A1%E5%9E%8B%E6%8E%A5%E5%85%A5 以及 OpenAPI 规范：https://docs.cloudbase.net/openapi/ai_model.v1.openapi.yaml

Online Debugging Tool

CloudBase platform provides an online debugging tool where you can test API interfaces without writing code:

  1. Visit the API documentation page
  2. Find the debugging tool entry
  3. Fill in environment ID and request parameters
  4. Click send request to view response

API Documentation References

⚠️ Always use searchKnowledgeBase tool to get OpenAPI Swagger specifications:

Use searchKnowledgeBase({ mode: "openapi", apiName: "<api-name>" }) with these API names:

  • auth - Authentication API
  • mysqldb - 关系型数据库 RESTful API (MySQL/PostgreSQL)
  • nosql - NoSQL RESTful API (文档型数据库)
  • functions - Cloud Functions API
  • cloudrun - CloudRun API
  • storage - Storage API
  • ai_model - AI 大模型接入 API

How to use the OpenAPI documentation:

  1. Call searchKnowledgeBase tool with the appropriate apiName
  2. Parse the returned YAML content to extract:
    • Endpoint paths (e.g., /v1/rdb/rest/{table})
    • HTTP methods (GET, POST, PATCH, DELETE)
    • Path parameters, query parameters, request body schemas
    • Response schemas and status codes
    • Authentication requirements
  3. Use the extracted information to construct accurate API calls
  4. Never assume endpoint structure - always verify against swagger documentation

Common Patterns

Reusable Shell Variables

env="your-env-id"
token="your-access-token-or-api-key"
base="https://${env}.api.tcloudbasegateway.com"

Common Request Pattern

curl -X GET "${base}/v1/rdb/rest/table_name" \
  -H "Authorization: Bearer ${token}" \
  -H "Content-Type: application/json"

Error Handling

Always check HTTP status codes and error response format:

{
  "code": "ERROR_CODE",
  "message": "Error message details",
  "requestId": "request-unique-id"
}

Common Authentication Flows

🌟 IMPORTANT: Default Authentication Method

When no specific signup/signin method is specified by the user, ALWAYS use Phone SMS Verification as the default and recommended method. It is:

  • ✅ The most user-friendly for Chinese users
  • ✅ No password to remember
  • ✅ Works for both new users (registration) and existing users (login)
  • ✅ Most secure with OTP verification
  • ✅ Supported by default in CloudBase

Phone Number Verification Code Login (Native Apps) ⭐ RECOMMENDED

This is the preferred authentication flow for native mobile apps (iOS/Android/Flutter/React Native):

┌─────────────────────────────────────────────────────────────────────────┐
│  Step 1: Send Verification Code                                        │
│  POST /auth/v1/verification                                             │
│  Body: { "phone_number": "+86 13800138000", "target": "ANY" }          │
│  ⚠️ IMPORTANT: phone_number MUST include "+86 " prefix WITH SPACE      │
│  Response: { "verification_id": "xxx", "expires_in": 600 }             │
│  📝 SAVE verification_id for next step!                                 │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│  Step 2: Verify Code                                                    │
│  POST /auth/v1/verification/verify                                      │
│  Body: { "verification_id": "<saved_id>", "verification_code": "123456" }│
│  Response: { "verification_token": "xxx" }                              │
│  📝 SAVE verification_token for login!                                  │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│  Step 3: Sign In with Token                                             │
│  POST /auth/v1/signin                                                   │
│  Body: { "verification_token": "<saved_token>" }                        │
│  Response: { "access_token": "xxx", "refresh_token": "xxx" }           │
└─────────────────────────────────────────────────────────────────────────┘

⚠️ Critical Notes:

  1. Phone number format: MUST be "+86 13800138000" with space after country code
  2. Save verification_id: Returned from Step 1, required for Step 2
  3. Save verification_token: Returned from Step 2, required for Step 3

Best Practices

  1. Always use URL encoding for query parameters containing special characters
  2. Include WHERE clauses for UPDATE and DELETE operations
  3. Use appropriate Prefer headers to control response format
  4. Handle errors gracefully by checking status codes and error responses
  5. Keep tokens secure - never expose API Keys in client-side code
  6. Use appropriate authentication method based on your use case:
    • AccessToken for user-specific operations
    • API Key for server-side admin operations
    • Publishable Key for public access (note: anonymous login is disabled by default for new environments)
  7. Phone number format: Always use international format with space: "+86 13800138000"
  8. Verification flow: Save verification_id from send step, use it in verify step

🔗 相关技巧

codex-review

通过集成专用代码审查模型实现自动化代码缺陷检测，支持在开发流程中识别安全漏洞、性能问题及代码异味，并可嵌入CI/CD流水线执行静态分析，提供结构化输出以供后续处理，适用于保障代码质量与维护安全合规的软件交付场景。

electron-chromium-upgrade

指导 Electron项目中 Chromium 版本升级的全流程，涵盖同步依赖时的补丁冲突解决与构建阶段的编译问题修复。通过反复执行同步与构建命令，定位并修复补丁应用及代码兼容性问题，确保所有更改按规范提交，最终实现 Electron 成功构建并启动。

cloudflare-r2

提供与 S3 兼容的对象存储服务，支持零出口流量费用的文件上传下载、跨区域数据迁移及生命周期管理，通过 Workers 深度集成实现低延迟访问，适用于构建高可用静态资源托管和大规模数据存储系统。

cursor-multi-repo

支持在 Cursor IDE 中统一管理多个代码仓库，通过多根工作区或单体仓库模式组织项目，实现跨仓库的规则继承、选择性索引配置及上下文感知，适用于复杂协作开发场景。