CloudBase official HTTP API client guide. This skill should be used when backends, scripts, or non-SDK clients must call CloudBase platform APIs over raw HTTP instead of using a platform SDK or MCP management tool.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
CloudBase official HTTP API client guide. This skill should be used when backends, scripts, or non-SDK clients must call CloudBase platform APIs over raw HTTP instead of using a platform SDK or MCP management tool.
version
2.20.1
alwaysApply
false
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.
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.
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)
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.
Determine the base URL
Use the correct domain based on region (domestic vs. international).
Default is domestic Shanghai region.
Set up authentication
Choose appropriate authentication method based on use case.
Add Authorization: Bearer <token> header to requests.
Reference OpenAPI Swagger documentation
MUST use searchKnowledgeBase tool to get OpenAPI specifications
Use the tool with mode=openapi and specify the apiName:
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:
Use searchKnowledgeBase tool to get OpenAPI documentation:
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:
- 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
Authorization
Bearer <token>
Authentication token
Authorization: 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.
⚠️ Important: DELETE requires a WHERE clause. Use query parameters to specify conditions.
Error Codes and HTTP Status Codes
Error Code
HTTP Status
Description
INVALID_PARAM
400
Invalid request parameters
INVALID_REQUEST
400
Invalid request content: missing permission fields, SQL execution errors, etc.
INVALID_REQUEST
406
Does not meet single record return constraint
PERMISSION_DENIED
401, 403
Authentication failed: 401 for identity authentication failure, 403 for authorization failure
RESOURCE_NOT_FOUND
404
Database instance or table not found
SYS_ERR
500
Internal system error
OPERATION_FAILED
503
Failed to establish database connection
RESOURCE_UNAVAILABLE
503
Database unavailable due to certain reasons
Response Format
All POST, PATCH, DELETE operations: Request header with Prefer: return=representation means there is a response body, without it means only response headers.
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 {}.
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、聚合查询、事务操作和数据库命令。
