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

• 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)

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

       - MySQL RESTful API

     • functions

       - Cloud Functions API

     • auth

       - Authentication API

     • cloudrun

       - CloudRun API

     • storage

       - Storage 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

searchKnowledgeBase

1. Use

   searchKnowledgeBase

   tool to get OpenAPI documentation:

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

2. Available API names:

   • mysqldb

     - MySQL RESTful API

   • functions

     - Cloud Functions API

   • auth

     - Authentication API

   • cloudrun

     - CloudRun API

   • storage

     - Storage 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.

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

• Validity: Long-term valid
• How to get: Get from CloudBase Platform/ApiKey Management Page

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

• Validity: Long-term valid
• How to get: Get from CloudBase Platform/ApiKey Management Page

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

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}

• envId

  is the environment ID

• instance

  is the database instance identifier

• schema

  is the database name

• table

  is the table name

/v1/rdb/rest/{table}

• 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

undefined

/v1/rdb/rest/{table}

💡 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.

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
  }'

/v1/rdb/rest/{table}

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.

/v1/rdb/rest/{table}

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.

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.

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

searchKnowledgeBase

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

• auth

  - Authentication API

• mysqldb

  - MySQL RESTful API

• functions

  - Cloud Functions API

• cloudrun

  - CloudRun API

• storage

  - Storage API

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

🌟 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

┌─────────────────────────────────────────────────────────────────────────┐
│  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" }           │
└─────────────────────────────────────────────────────────────────────────┘

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

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/anonymous access
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