{ "swagger": "2.0", "info": { "title": "TiDB Cloud Starter and Essential Database Audit Logging Open API", "description": "TiDB Cloud Starter and Essential Database Audit Logging Open API", "version": "v1beta1" }, "tags": [ { "name": "DatabaseAuditLogService" } ], "host": "serverless.tidbapi.com", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/v1beta1/clusters/{clusterId}/auditLog/files": { "get": { "summary": "List audit log files, only available when audit logs are stored in TiDB Cloud.", "operationId": "DatabaseAuditLogService_ListAuditLogFiles", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ListAuditLogFilesResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster.", "in": "path", "required": true, "type": "string" }, { "name": "date", "description": "The UTC date of the audit logs in the format of `YYYY-MM-DD` (e.g. 2025-01-01).", "in": "query", "required": false, "type": "string" }, { "name": "pageSize", "description": "The maximum number to return, default is 100, and the maximum is 1000.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "pageToken", "description": "The page token from the previous response for pagination.", "in": "query", "required": false, "type": "string" } ], "tags": [ "DatabaseAuditLogService" ] } }, "/v1beta1/clusters/{clusterId}/auditLog/files:download": { "post": { "summary": "Generate audit log files download url, only available when audit logs are stored in TiDB Cloud.", "operationId": "DatabaseAuditLogService_DownloadAuditLogFiles", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/DownloadAuditLogFilesResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The ID of the cluster.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DatabaseAuditLogService.DownloadAuditLogFilesBody" } } ], "tags": [ "DatabaseAuditLogService" ] } }, "/v1beta1/clusters/{clusterId}/auditLog/filterRules/{filterRuleId}": { "get": { "summary": "Get audit log filter rule.", "operationId": "DatabaseAuditLogService_GetAuditLogFilterRule", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogFilterRule" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "filterRuleId", "description": "The id of the filter rule.", "in": "path", "required": true, "type": "string" } ], "tags": [ "DatabaseAuditLogService" ] }, "delete": { "summary": "Delete audit log filter rule.", "operationId": "DatabaseAuditLogService_DeleteAuditLogFilterRule", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogFilterRule" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "filterRuleId", "description": "The id of the filter rule.", "in": "path", "required": true, "type": "string" } ], "tags": [ "DatabaseAuditLogService" ] }, "patch": { "summary": "Update audit log filter rule.", "operationId": "DatabaseAuditLogService_UpdateAuditLogFilterRule", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogFilterRule" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "filterRuleId", "description": "The id of the filter rule.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DatabaseAuditLogService.UpdateAuditLogFilterRuleBody" } } ], "tags": [ "DatabaseAuditLogService" ] } }, "/v1beta1/clusters/{clusterId}/auditLog/filterRules": { "get": { "summary": "List audit log filter rules.", "operationId": "DatabaseAuditLogService_ListAuditLogFilterRules", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ListAuditLogFilterRulesResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "pageSize", "description": "The maximum number to return, default is 10, and the maximum is 100.", "in": "query", "required": false, "type": "integer", "format": "int32" }, { "name": "pageToken", "description": "The page token from the previous response for pagination.", "in": "query", "required": false, "type": "string" } ], "tags": [ "DatabaseAuditLogService" ] }, "post": { "summary": "Create audit log filter rule.", "operationId": "DatabaseAuditLogService_CreateAuditLogFilterRule", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogFilterRule" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DatabaseAuditLogService.CreateAuditLogFilterRuleBody" } } ], "tags": [ "DatabaseAuditLogService" ] } }, "/v1beta1/clusters/{clusterId}/auditLog/config": { "get": { "summary": "Get audit log configuration.", "operationId": "DatabaseAuditLogService_GetAuditLogConfig", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogConfig" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" } ], "tags": [ "DatabaseAuditLogService" ] }, "patch": { "summary": "Update audit log configuration.", "operationId": "DatabaseAuditLogService_UpdateAuditLogConfig", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/AuditLogConfig" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/Status" } } }, "parameters": [ { "name": "clusterId", "description": "The cluster ID", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/DatabaseAuditLogService.UpdateAuditLogConfigBody" } } ], "tags": [ "DatabaseAuditLogService" ] } } }, "definitions": { "Any": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "AuditLogConfig": { "type": "object", "properties": { "clusterId": { "type": "string", "description": "The ID of the cluster.", "readOnly": true }, "enabled": { "type": "boolean", "x-nullable": true, "description": "Whether audit log is enabled." }, "unredacted": { "type": "boolean", "x-nullable": true, "description": "Whether unredacted the audit log." }, "cloudStorage": { "description": "The cloud storage for audit logs.", "allOf": [ { "$ref": "#/definitions/common.CloudStorage" } ] }, "rotationIntervalMinutes": { "type": "integer", "format": "int32", "description": "The rotation interval in minutes for audit logs. Default to 60 minutes." }, "rotationSizeMib": { "type": "integer", "format": "int32", "description": "The rotation size in MiB for audit logs. Default to 100 MiB." } } }, "AuditLogFile": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the audit log." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "The size in bytes of the audit log." }, "url": { "type": "string", "description": "download url of the audit log." }, "createTime": { "type": "string", "format": "date-time", "description": "The create time of the audit log." } } }, "AuditLogFilter": { "type": "object", "properties": { "classes": { "type": "array", "items": { "type": "string" }, "description": "Classes to include in the filter combined with an OR relationship." }, "tables": { "type": "array", "items": { "type": "string" }, "description": "Tables to include in the filter combined with an OR relationship." }, "statusCodes": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Status codes to include in the filter combined with an OR relationship." } }, "description": "Message for filter, only the entry matching all the conditions will be audit logged." }, "AuditLogFilterRule": { "type": "object", "properties": { "filterRuleId": { "type": "string", "description": "The audit log filter rule ID.", "readOnly": true }, "clusterId": { "type": "string", "description": "The cluster ID.", "readOnly": true }, "displayName": { "type": "string", "description": "Unique name of the filter rule within a cluster." }, "users": { "type": "array", "items": { "type": "string" }, "title": "Database users in the format @ or (host defaults to %), e.g., %@%, 4C3z3cdMX8iXks5.root" }, "filters": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AuditLogFilter" }, "description": "List of filters combined with an OR relationship. Set filters to [{}] will filter all logs." }, "disabled": { "type": "boolean", "description": "Indicates whether the filter rule is disabled.", "readOnly": true }, "createTime": { "type": "string", "format": "date-time", "description": "Timestamp when the filter rule was created.", "readOnly": true }, "updateTime": { "type": "string", "format": "date-time", "x-nullable": true, "description": "Timestamp when the filter rule was updated.", "readOnly": true } }, "required": [ "displayName", "users", "filters" ] }, "AzureBlobCloudStorage": { "type": "object", "properties": { "uri": { "type": "string", "description": "Required. The Azure Blob URI. For example: azure://.blob.core.windows.net/// or https://.blob.core.windows.net///." }, "authType": { "description": "Required. The auth method of Azure Blob.", "allOf": [ { "$ref": "#/definitions/AzureBlobCloudStorage.AzureBlobAuthType" } ] }, "sasToken": { "type": "string", "description": "Optional. The sas token." } }, "required": [ "uri", "authType" ] }, "AzureBlobCloudStorage.AzureBlobAuthType": { "type": "string", "enum": [ "SAS_TOKEN" ], "description": " - SAS_TOKEN: The access method is sas token." }, "CloudStorageType.Enum": { "type": "string", "enum": [ "TIDB_CLOUD", "S3", "GCS", "AZURE_BLOB", "OSS" ], "description": " - TIDB_CLOUD: TiDB Cloud's own cloud storage.\n - S3: Amazon S3 cloud storage.\n - GCS: Google Cloud Storage.\n - AZURE_BLOB: Azure Blob Storage.\n - OSS: Alibaba Cloud OSS." }, "DatabaseAuditLogService.CreateAuditLogFilterRuleBody": { "type": "object", "properties": { "filterRule": { "title": "The filter rule to create", "allOf": [ { "$ref": "#/definitions/AuditLogFilterRule" } ] } }, "required": [ "filterRule" ] }, "DatabaseAuditLogService.DownloadAuditLogFilesBody": { "type": "object", "properties": { "auditLogFileNames": { "type": "array", "items": { "type": "string" }, "description": "The name of the audit log files to download. Up to 100 audit logs can be downloaded at the same time." } }, "required": [ "auditLogFileNames" ] }, "DatabaseAuditLogService.UpdateAuditLogConfigBody": { "type": "object", "properties": { "auditLogConfig": { "description": "The audit log configuration to update.", "allOf": [ { "$ref": "#/definitions/AuditLogConfig" } ] } }, "required": [ "auditLogConfig" ] }, "DatabaseAuditLogService.UpdateAuditLogFilterRuleBody": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AuditLogFilter" }, "description": "List of filters combined with an OR relationship. Set filters to [{}] will filter all logs." }, "users": { "type": "array", "items": { "type": "string" }, "title": "Database users in the format @ or (host defaults to %), e.g., %@%, 4C3z3cdMX8iXks5.root" }, "disabled": { "type": "boolean", "x-nullable": true, "description": "Indicates whether the filter rule is disabled." }, "displayName": { "type": "string", "description": "Display name of the filter rule." } } }, "DownloadAuditLogFilesResponse": { "type": "object", "properties": { "auditLogFiles": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AuditLogFile" }, "description": "The audit logs with the download url." } } }, "GCSCloudStorage": { "type": "object", "properties": { "uri": { "type": "string", "description": "Required. The GCS URI. For example: gs:////." }, "authType": { "description": "Required. The auth method of GCS.", "allOf": [ { "$ref": "#/definitions/GCSCloudStorage.GCSAuthType" } ] }, "serviceAccountKey": { "type": "string", "description": "Required. The service account key." } }, "required": [ "uri", "authType" ] }, "GCSCloudStorage.GCSAuthType": { "type": "string", "enum": [ "SERVICE_ACCOUNT_KEY" ], "description": " - SERVICE_ACCOUNT_KEY: The access method is service account key." }, "ListAuditLogFilesResponse": { "type": "object", "properties": { "auditLogFiles": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AuditLogFile" }, "description": "The audit log files without the download url." }, "nextPageToken": { "type": "string", "description": "Token provided to retrieve the next page of results." } } }, "ListAuditLogFilterRulesResponse": { "type": "object", "properties": { "filterRules": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/AuditLogFilterRule" } }, "nextPageToken": { "type": "string" }, "totalSize": { "type": "integer", "format": "int64" } } }, "OSSCloudStorage": { "type": "object", "properties": { "uri": { "type": "string", "description": "Required. The OSS URI. For example: oss:////." }, "authType": { "description": "Required. The auth method of OSS.", "allOf": [ { "$ref": "#/definitions/OSSCloudStorage.OSSAuthType" } ] }, "accessKey": { "description": "Optional. The access key.", "allOf": [ { "$ref": "#/definitions/OSSCloudStorage.AccessKey" } ] }, "roleArn": { "type": "string", "description": "Optional. The role arn." } }, "required": [ "uri", "authType" ] }, "OSSCloudStorage.AccessKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Required. The access key id." }, "secret": { "type": "string", "description": "Required. The access key secret. This field is input-only." } }, "required": [ "id", "secret" ] }, "OSSCloudStorage.OSSAuthType": { "type": "string", "enum": [ "ACCESS_KEY", "ROLE_ARN" ], "description": " - ACCESS_KEY: The access method is access key.\n - ROLE_ARN: The access method is role arn." }, "S3CloudStorage": { "type": "object", "properties": { "uri": { "type": "string", "description": "Required. The URI of the S3 folder. For example: s3:////." }, "authType": { "description": "Required. The auth method of S3.", "allOf": [ { "$ref": "#/definitions/S3CloudStorage.S3AuthType" } ] }, "accessKey": { "description": "Optional. The access key of the S3.", "allOf": [ { "$ref": "#/definitions/S3CloudStorage.AccessKey" } ] }, "roleArn": { "type": "string", "description": "Optional. The role arn of the S3." } }, "required": [ "uri", "authType" ] }, "S3CloudStorage.AccessKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Required. The access key id of the S3." }, "secret": { "type": "string", "description": "Required. The secret access key of the S3." } }, "required": [ "id", "secret" ] }, "S3CloudStorage.S3AuthType": { "type": "string", "enum": [ "ROLE_ARN", "ACCESS_KEY" ], "description": " - ROLE_ARN: The access method is role arn.\n - ACCESS_KEY: The access method is access key." }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/Any" } } } }, "common.CloudStorage": { "type": "object", "properties": { "type": { "description": "Required. The type of cloud storage.", "allOf": [ { "$ref": "#/definitions/CloudStorageType.Enum" } ] }, "s3": { "$ref": "#/definitions/S3CloudStorage" }, "gcs": { "$ref": "#/definitions/GCSCloudStorage" }, "azureBlob": { "$ref": "#/definitions/AzureBlobCloudStorage" }, "oss": { "$ref": "#/definitions/OSSCloudStorage" } }, "description": "Message for cloud storage.", "required": [ "type" ] } } }