Version: 1.0.0

• OpenAPI Spec

NoSQL RESTful API

Overview

RESTful HTTP API for the Document Database (NoSQL), providing collection management, document CRUD, aggregation queries, transaction operations, and database command execution.

Request Domain

https://{envId}.api.tcloudbasegateway.com/v1/database/instances/{instance}/databases/{database}/

URL path parameters:

• envId: Environment ID
• instance: Instance ID, cannot be empty. Use (default) for the default instance (note: the parentheses are part of the value and must be included)
• database: Database name, cannot be empty. Use (default) for the default database (note: the parentheses are part of the value and must be included)

Examples:

• Access the default instance's default database: /v1/database/instances/(default)/databases/(default)/
• Access instance test_instance's default database: /v1/database/instances/test_instance/databases/(default)/
• Access instance test_instance's database mydb: /v1/database/instances/test_instance/databases/mydb/

EJSON Format

Request bodies support both Relaxed EJSON and Strict EJSON formats. Response bodies are always in Strict EJSON format.

EJSON (Extended JSON) is MongoDB's extended JSON format that supports data types not available in standard JSON:

• ObjectId: {"$oid": "507f1f77bcf86cd799439011"}
• Date: {"$date": {"$numberLong": "1736929200000"}}
• Int: {"$numberInt": "12345"}
• Long: {"$numberLong": "9223372036854775807"}
• Decimal128: {"$numberDecimal": "123.456"}
• Binary: {"$binary": {"base64": "...", "subType": "00"}}
• RegExp: {"$regex": "pattern", "$options": "i"}

Getting Started

All API calls require an AccessToken in the format Authorization: Bearer <token>. For token acquisition, refer to: https://docs.cloudbase.net/http-api/basic/access-token

Error Codes and HTTP Status Codes

Error Code	HTTP Status	Description
INVALID_PARAM	400	Invalid or missing parameter
DATABASE_PERMISSION_DENIED	401	Database permission denied
DATABASE_INVALID_OPERRATOR	403	Unsupported operation
DATABASE_COLLECTION_NOT_EXIST	404	Collection does not exist
DOCUMENT_NOT_FOUND	404	Document not found (single document operations only)
DATABASE_COLLECTION_ALREADY_EXIST	409	Collection already exists
DATABASE_DUPLICATE_WRITE	409	Unique index conflict
EXCEED_REQUEST_LIMIT	422	Request quota exceeded
EXCEED_CONCURRENT_REQUEST_LIMIT	422	Concurrent connection limit exceeded
DATABASE_REQUEST_FAILED	500	Database request failed
SYS_ERR	500	Internal system error
DATABASE_TRANSACTION_CONFLICT	503	Transaction conflict
DATABASE_TRANSACTION_FAIL	503	Transaction execution failed
DATABASE_TIMEOUT	504	Database operation timeout