Query database list¶

Returns a list of readable databases under the specified Catalog.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/database/list

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the catalog list to obtain the target catalog ID.

Set the operation-specific values used in the request:

$CATALOG_ID: Catalog ID of the database to be listed.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/database/list" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": '"$CATALOG_ID"'
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`id`	integer	Yes	Catalog ID.

Successful response¶

On success, returns 200 and a list of databases readable by the current identity.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "list": [
      {
        "id": 2,
        "name": "orders",
        "description": "订单库",
        "volume_count": 1,
        "file_count": 2,
        "table_count": 3,
        "created_at": "2026-08-18T10:00:00Z",
        "updated_at": "2026-08-18T10:00:00Z",
        "created_by": "user-001",
        "updated_by": "user-001",
        "reserved": false,
        "allowed_actions": ["database.read"]
      }
    ]
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.list`	object[]	Database list; empty array when there is no readable database.
`data.list[].id`	integer	Database ID.
`data.list[].name`	string	Database name.
`data.list[].description`	string	Database description.
`data.list[].display_name`	string	Database display name; returned if there is a value.
`data.list[].display_description`	string	Database display description; returned if there is a value.
`data.list[].volume_count`	integer	Number of subordinate volumes.
`data.list[].file_count`	integer	Number of subordinate files.
`data.list[].table_count`	integer	Number of subordinate tables.
`data.list[].created_at`	string	Creation time.
`data.list[].updated_at`	string	Update time.
`data.list[].created_by`	string	Creator ID.
`data.list[].updated_by`	string	Updater ID.
`data.list[].reserved`	boolean	Whether to retain the database.
`data.list[].is_pub`	boolean	Whether it is a published database.
`data.list[].is_sub`	boolean	Whether the database is subscribed.
`data.list[].allowed_actions`	string[]	Operations allowed by the current identity.

In this document, [] after a type means an array; for example, object[] is an array of objects. In field paths, [] means each item in an array; for example, data.list[].id is the id field of each item in data.list.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The request body or Catalog ID is invalid.	Use positive integer IDs from the Catalog list.
`403`	`ErrForbidden`	The current identity does not have permission to read the Catalog.	Requesting permission to `catalog.read`.
`404`	`ErrObjectNotFound`	Catalog does not exist or cannot be read.	Verify Catalog ID and workspace.
`500`	`ErrServer`	The server failed to read the database list.	Try again later.

Follow-up operations¶

Use data.list[].id Query database details.

Last updated on Sep 15, 2026