openapi: 3.0.3
info:
  title: 云存储
  description: >-
    ### Feature Overview

    This set of open APIs provides the ability to integrate with cloud storage (COS services). You can call these open APIs to obtain object upload information, download links, and more. All APIs in this set support batch operations.

    > **This API is for classic-mode environments.** If you are using a PG environment, see the [PG cloud storage HTTP API](/http-api/storage-pg/pg-storage-api), which exposes full Bucket / Object CRUD, signed URLs, object metadata, multipart uploads, and is gated by RLS.

    ### Integration Guide

    To call the following interfaces, you need to pass an AccessToken in the format `Authorization: Bearer <token>`. For how to obtain the token, refer to: https://docs.cloudbase.net/http-api/basic/access-token

    ### HTTP Status Codes

    Depending on the returned results, the following status codes may appear: `2xx`, `4xx`, `5xx`.

    ### Error Codes

    The following lists the specific error codes for this set of APIs. For a complete list, refer to: https://docs.cloudbase.net/error-code/service

    <table>
      <thead>
      <tr>
        <td>Error Code</td>
        <td>Meaning</td>
      </tr>
      </thead>
      <tr>
        <td>STORAGE_EXCEED_AUTHORITY</td>
        <td>No permission to perform the corresponding operation on this object</td>
      </tr>
      <tr>
        <td>COS_ACTION_FAILED</td>
        <td>Object storage operation execution failed</td>
      </tr>
      <tr>
        <td>OBJECT_NOT_EXIST</td>
        <td>The requested object does not exist and the specified operation cannot be performed</td>
      </tr>
      <tr>
        <td>OBJECT_ALREADY_EXIST</td>
        <td>The object already exists and the specified operation cannot be performed</td>
      </tr>
      <tr>
        <td>OBJECT_BATCH_TOO_LARGE</td>
        <td>The number of objects processed in a single batch is too large. Try reducing the number of objects processed per batch.</td>
      </tr>
    </table>
  contact:
    name: TCB
    url: https://cloud.tencent.com/product/tcb
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://{envId}.api.tcloudbasegateway.com
    description: TCB OpenAPI endpoint
    variables:
      envId:
        default: "your-envId"
        description: Environment ID
paths:
  /v1/storages/get-objects-upload-info:
    post:
      tags:
        - 云存储对象操作
      externalDocs:
        description: For a complete list of error codes, refer to https://docs.cloudbase.net/error-code/service
        url: https://docs.cloudbase.net/error-code/service
      operationId: get-objects-upload-info
      summary: Get object upload information
      description: |-
        Batch obtain information required to upload objects.

        **This API is subject to cloud storage bucket permission configuration and identity authentication and authorization. Ensure the requesting identity has the necessary permissions for the corresponding resources.**

        For cloud storage permission configuration, see [Cloud Storage Basic Permissions](/storage/data-permission) and [Cloud Storage Security Rules](/storage/security-rules).

        > 💡 Tip: If cloud storage operations are blocked by basic permissions or security rules, you may encounter the error code:
        >    [STORAGE_EXCEED_AUTHORITY](/error-code/STORAGE_EXCEED_AUTHORITY)

        > 💡 Tip: If cloud storage operations are blocked by the identity authentication mechanism, you may encounter the error code:
        >    [ACTION_FORBIDDEN](/error-code/ACTION_FORBIDDEN)

        After obtaining the upload information, use the response data on the client side to complete the direct upload to the storage bucket. Example steps are as follows:

        **Step 1: Obtain upload information via HTTP API**

        ```bash
        curl -L 'https://{envId}.api.tcloudbasegateway.com/v1/storages/get-objects-upload-info' \
          -H 'Content-Type: application/json' \
          -H 'Authorization: Bearer <ACCESS_TOKEN>' \
          -d '[
            {
              "objectId": "filename.jpg"
            }
          ]'
        ```

        **Response Structure**: The interface returns an array. Successful items contain the fields required for upload, while failed items contain `code`/`message` for troubleshooting.

        ```json
        [
          {
            "objectId": "dirname/filename.jpg",
            "uploadUrl": "https://url/filename.jpg",
            "authorization": "q-sign-algorithm=sha1&q-ak=...",
            "token": "xxx",
            "cloudObjectMeta": "xxx",
            "downloadUrl": "https://url/filename.jpg?sign=xxx&t=yyy",
            "downloadUrlEncoded": "https://url/filename.jpg?sign=xxx&t=yyy",
            "cloudObjectId": "cloud://your-envId.bucket/filename.jpg"
          },
          {
            "code": "COS_ACTION_FAILED",
            "message": "Execute COS action failed."
          }
        ]
        ```

        **Step 2: Extract the required fields from the response and complete the file upload**

        For example, use tools like `jq` to extract fields from the first successful item in the array:

        ```bash
        response=$(curl ...)
        upload_url=$(echo "$response" | jq -r '.[0].uploadUrl')
        auth=$(echo "$response" | jq -r '.[0].authorization')
        token=$(echo "$response" | jq -r '.[0].token')
        meta=$(echo "$response" | jq -r '.[0].cloudObjectMeta')
        ```
        Then use the above fields to upload the file with a **PUT** request to the corresponding URL:
        ```bash
        curl -X PUT "$upload_url" \
          -H "Authorization: $auth" \
          -H "X-Cos-Security-Token: $token" \
          -H "X-Cos-Meta-Fileid: $meta" \
          --data-binary @filename.jpg
        ```
      requestBody:
        $ref: "#/components/requestBodies/v1GetObjectsUploadInfoRequestData"
      responses:
        "200":
          description: Returned when the call is successful
          headers:
            X-Request-Id:
              schema:
                type: string
              description: "Request ID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetObjectsUploadInfoResponseData"

        "default":
          $ref: "#/components/responses/CommonErrorResponse"

  /v1/storages/get-objects-download-info:
    post:
      tags:
        - 云存储对象操作
      externalDocs:
        description: For a complete list of error codes, refer to https://docs.cloudbase.net/error-code/service
        url: https://docs.cloudbase.net/error-code/service
      operationId: get-objects-download-info
      summary: Get object download information
      description: |-
        Batch obtain object download URLs.

        **This API is subject to cloud storage bucket permission configuration and identity authentication and authorization. Ensure the requesting identity has the necessary permissions for the corresponding resources.**

        For cloud storage permission configuration, see [Cloud Storage Basic Permissions](/storage/data-permission) and [Cloud Storage Security Rules](/storage/security-rules).

        > 💡 Tip: If cloud storage operations are blocked by basic permissions or security rules, you may encounter the error code:
        >    [STORAGE_EXCEED_AUTHORITY](/error-code/STORAGE_EXCEED_AUTHORITY)

        > 💡 Tip: If cloud storage operations are blocked by the identity authentication mechanism, you may encounter the error code:
        >    [ACTION_FORBIDDEN](/error-code/ACTION_FORBIDDEN)

      requestBody:
        $ref: "#/components/requestBodies/v1GetObjectDownloadInfoRequestData"
      responses:
        "200":
          description: Returned when the call is successful
          headers:
            X-Request-Id:
              schema:
                type: string
              description: "Request ID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetObjectDownloadInfoResponseData"

        "default":
          $ref: "#/components/responses/CommonErrorResponse"

  /v1/storages/delete-objects:
    post:
      tags:
        - 云存储对象操作
      externalDocs:
        description: For a complete list of error codes, refer to [https://docs.cloudbase.net/error-code/service](https://docs.cloudbase.net/error-code/service)
        url: https://docs.cloudbase.net/error-code/service
      operationId: delete-objects
      summary: Delete objects
      description: |-
        Batch delete objects.

        **This API is subject to cloud storage bucket permission configuration and identity authentication and authorization. Ensure the requesting identity has the necessary permissions for the corresponding resources.**

        For cloud storage permission configuration, see [Cloud Storage Basic Permissions](/storage/data-permission) and [Cloud Storage Security Rules](/storage/security-rules).

        > 💡 Tip: If cloud storage operations are blocked by basic permissions or security rules, you may encounter the error code:
        >    [STORAGE_EXCEED_AUTHORITY](/error-code/STORAGE_EXCEED_AUTHORITY)

        > 💡 Tip: If cloud storage operations are blocked by the identity authentication mechanism, you may encounter the error code:
        >    [ACTION_FORBIDDEN](/error-code/ACTION_FORBIDDEN)

      requestBody:
        $ref: "#/components/requestBodies/v1DeleteObjectsRequestData"
      responses:
        "200":
          description: Returned when the call is successful
          headers:
            X-Request-Id:
              schema:
                type: string
              description: "Request ID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1DeleteObjectsResponseData"

        "default":
          $ref: "#/components/responses/CommonErrorResponse"

  /v1/storages/copy-objects:
    post:
      tags:
        - 云存储对象操作
      externalDocs:
        description: For a complete list of error codes, refer to https://docs.cloudbase.net/error-code/service
        url: https://docs.cloudbase.net/error-code/service
      operationId: copy-objects
      summary: Copy objects
      description: |
        **Note: This interface can only be called by administrators.**

        Batch copy specified objects to the target path, with optional parameters to control whether to overwrite existing objects with the same name at the target path or delete the original objects after copying.

      requestBody:
        $ref: "#/components/requestBodies/v1CopyObjects"
      responses:
        "200":
          description: Returned when the call is successful
          headers:
            X-Request-Id:
              schema:
                type: string
              description: "Request ID"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1CopyObjectsResponseData"

        "default":
          $ref: "#/components/responses/CommonErrorResponse"

components:
  responses:
    InvalidRequest:
      description: Request failed
      headers:
        X-Request-Id:
          schema:
            type: string
          description: "Request ID"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CommonErrorResponse"
          examples:
            AIModelConfigMissing:
              summary: Missing necessary configuration for calling the model, such as token, clientID, etc. (400)
              value:
                code: "AI_MODEL_CONFIG_MISSING"
                message: "xxx"
                requestId: "xxx"
            AIModelParamInvalid:
              summary: Invalid parameters for calling the model (400)
              value:
                code: "AI_MODEL_PARAM_INVALID"
                message: "xxx"
                requestId: "xxx"
            AIModelRequestFailed:
              summary: Failed to request the model (400)
              value:
                code: "AI_MODEL_REQUEST_FAILED"
                message: "xxx"
                requestId: "xxx"
    RequestFailed:
      description: Request failed
      headers:
        X-Request-Id:
          schema:
            type: string
          description: "Request ID"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CommonErrorResponse"
          examples:
            FeatureNotConfigured:
              summary: Large model not enabled (404)
              value:
                code: "ENV_FEATURE_NOT_CONFIGURED"
                message: "xxx"
                requestId: "xxx"
            AIModelNotFound:
              summary: Specified model not found (404)
              value:
                code: "AI_MODEL_NOT_FOUND"
                message: "xxx"
                requestId: "xxx"
    CommonErrorResponse:
      description: General error information, see https://docs.cloudbase.net/error-code/service for details
      headers:
        X-Request-Id:
          schema:
            type: string
          description: "Request ID"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CommonErrorResponse"
          examples:
            InvalidHost:
              summary: Invalid request address
              value:
                code: "INVALID_HOST"
                message: "xxx"
                requestId: "xxx"

  requestBodies:
    v1GetObjectsUploadInfoRequestData:
      required: true
      description: Upload object request parameters, array format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/v1GetObjectsUploadInfoRequestData"
    v1GetObjectDownloadInfoRequestData:
      required: true
      description: Download object request parameters, array format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/v1GetObjectDownloadInfoRequestData"
    v1DeleteObjectsRequestData:
      required: true
      description: Delete object request parameters, array format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/v1DeleteObjectsRequestData"
    v1CopyObjects:
      required: true
      description: Batch copy object request parameters, array format
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/v1CopyObjectsRequestData"

  schemas:
    v1GetObjectsUploadInfoRequestItem:
      type: object
      example:
        [
          {
            "objectId": "file.jpg",
            "signedHeader": { "content-md5": ["here-goes-md5"] },
          },
          { "object": "already-exsited-object" },
        ]
      properties:
        objectId:
          type: string
          title: Object ID, e.g., file name
          example: "file.jpg"
        signedHeader:
          type: object
          title: Header fields to be signed
          example: { "content-md5": ["here-goes-md5"] }
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - objectId
    v1GetObjectsUploadInfoRequestData:
      type: array
      items:
        $ref: "#/components/schemas/v1GetObjectsUploadInfoRequestItem"
      description: Upload object request parameters, array format
      example:
        [
          {
            "objectId": "file.jpg",
            "signedHeader": { "content-md5": ["here-goes-md5"] },
          },
          { "object": "already-exsited-object" },
        ]
    v1GetObjectsUploadInfoResponseItem:
      type: object
      oneOf:
        - $ref: "#/components/schemas/v1GetObjectsUploadInfoResponseItemSuccess"
        - $ref: "#/components/schemas/v1GetObjectsUploadInfoResponseItemError"
    v1GetObjectsUploadInfoResponseItemError:
      type: object
      properties:
        code:
          type: string
          example: "COS_ACTION_FAILED"
          title: Error code returned when the request for this object fails
        message:
          type: string
          example: "Execute COS action failed."
          title: Error message returned when the request for this object fails
      example:
        { "code": "COS_ACTION_FAILED", "message": "Execute COS action failed." }
    v1GetObjectsUploadInfoResponseItemSuccess:
      type: object
      properties:
        uploadUrl:
          type: string
          format: uri
          example: "https://url/file.jpg%3FExpires%3D123"
          title: Object upload URL
        downloadUrl:
          type: string
          format: uri
          example: "https://url/file.jpg?Expires=123"
          title: Download URL after object upload (not URL-encoded)
        downloadUrlEncoded:
          type: string
          format: uri
          example: "https://url/file.jpg%3FExpires%3D123"
          title: Download URL after object upload (URL-encoded)
        token:
          type: string
          example: "token"
          title: Token required for upload, fill in the X-Cos-Security-Token header
        authorization:
          type: string
          example: "q-sign-algorithm=sha1&q-ak="
          title: Authorization information required for upload, fill in the Authorization header
        cloudObjectMeta:
          type: string
          example: "metadata"
          title: Metadata information required for upload, fill in the X-Cos-Meta-Fileid header
        cloudObjectId:
          type: string
          example: "cloud://your-envId.bucket/file.jpg?Expires=123"
          title: Cloud object ID after object upload
        objectId:
          type: string
          example: "file.jpg"
          title: Object ID for this request
      description: Upload object response information
      example:
        {
          "uploadUrl": "https://url/file.jpg%3FExpires%3D123",
          "downloadUrl": "https://url/file.jpg?Expires=123",
          "downloadUrlEncoded": "https://url/file.jpg%3FExpires%3D123",
          "token": "token",
          "authorization": "q-sign-algorithm=sha1&q-ak=",
          "cloudObjectMeta": "metadata",
          "cloudObjectId": "cloud://your-envId.bucket/file.jpg?Expires=123",
          "objectId": "file.jpg",
        }
    v1GetObjectsUploadInfoResponseData:
      type: array
      items:
        $ref: "#/components/schemas/v1GetObjectsUploadInfoResponseItem"
      description: Upload object response results, array format
      example:
        [
          {
            "uploadUrl": "https://url/file.jpg%3FExpires%3D123",
            "downloadUrl": "https://url/file.jpg?Expires=123",
            "downloadUrlEncoded": "https://url/file.jpg%3FExpires%3D123",
            "token": "token",
            "authorization": "q-sign-algorithm=sha1&q-ak=",
            "cloudObjectMeta": "metadata",
            "cloudObjectId": "cloud://your-envId.bucket/file.jpg?Expires=123",
            "objectId": "file.jpg",
          },
          {
            "code": "COS_ACTION_FAILED",
            "message": "Execute COS action failed.",
          },
        ]
    v1GetObjectDownloadInfoRequestItem:
      type: object
      example:
        [
          { "objectId": "cloud://your-envId.bucket/file.jpg" },
          { "objectId": "not-valid" },
        ]
      properties:
        cloudObjectId:
          type: string
          title: Cloud object ID
    v1GetObjectDownloadInfoRequestData:
      type: array
      items:
        $ref: "#/components/schemas/v1GetObjectDownloadInfoRequestItem"
      description: Download object request parameters, array format
      example:
        [
          { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" },
          { "cloudObjectId": "not-valid" },
        ]
    v1GetObjectDownloadInfoResponseItemError:
      type: object
      properties:
        code:
          example: "INVALID_PARAM"
          type: string
          title: Error code returned when the request for this object fails
        message:
          example: "Invalid request param."
          type: string
          title: Error message returned when the request for this object fails
      example: { "code": "INVALID_PARAM", "message": "Invalid request param." }
    v1GetObjectDownloadInfoResponseItemSuccess:
      type: object
      properties:
        cloudObjectId:
          type: string
          title: Cloud object ID
          example: "cloud://your-envId.bucket/file.jpg"
        downloadUrl:
          title: Download URL after object upload (not URL-encoded)
          type: string
          example: "https://url/file.jpg"
        downloadUrlEncoded:
          title: Download URL after object upload (URL-encoded)
          type: string
          example: "https://url/file.jpg"
      example:
        {
          "cloudObjectId": "cloud://your-envId.bucket/file.jpg",
          "downloadUrl": "https://url/file.jpg",
          "downloadUrlEncoded": "https://url/file.jpg",
        }
    v1GetObjectDownloadInfoResponseItem:
      type: object
      oneOf:
        - $ref: "#/components/schemas/v1GetObjectDownloadInfoResponseItemSuccess"
        - $ref: "#/components/schemas/v1GetObjectDownloadInfoResponseItemError"
    v1GetObjectDownloadInfoResponseData:
      type: array
      items:
        $ref: "#/components/schemas/v1GetObjectDownloadInfoResponseItem"
      description: Download object response results, array format
      example:
        [
          {
            "cloudObjectId": "cloud://your-envId.bucket/file.jpg",
            "downloadUrl": "https://url/file.jpg",
            "downloadUrlEncoded": "https://url/file.jpg",
          },
          { "code": "INVALID_PARAM", "message": "Invalid request param." },
        ]
    v1DeleteObjectsRequestItem:
      type: object
      properties:
        cloudObjectId:
          type: string
          title: Cloud object ID
    v1DeleteObjectsRequestData:
      example:
        [
          { "cloudObjectId": "cloud://your-envId.bucket/not-exist" },
          { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" },
        ]
      type: array
      items:
        $ref: "#/components/schemas/v1DeleteObjectsRequestItem"
      description: Delete object request parameters, array format
    v1DeleteObjectsResponseItemError:
      type: object
      example:
        {
          "cloudObjectId": "cloud://your-envId.bucket/not-exist",
          "code": "OBJECT_NOT_EXIST",
          "message": "Storage object not exists.",
        }
      properties:
        code:
          type: string
          title: Error code returned when the request for this object fails
        message:
          type: string
          title: Error description returned when the request for this object fails
        cloudObjectId:
          type: string
          title: Cloud object ID operated in this request
    v1DeleteObjectsResponseItemSuccess:
      type: object
      example: { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" }
      properties:
        cloudObjectId:
          type: string
          title: Cloud object ID
    v1DeleteObjectsResponseItem:
      type: object
      oneOf:
        - $ref: "#/components/schemas/v1DeleteObjectsResponseItemSuccess"
        - $ref: "#/components/schemas/v1DeleteObjectsResponseItemError"
    v1DeleteObjectsResponseData:
      example:
        [
          {
            "cloudObjectId": "cloud://your-envId.bucket/not-exist",
            "code": "OBJECT_NOT_EXIST",
            "message": "Storage object not exists.",
          },
          { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" },
        ]
      type: array
      items:
        $ref: "#/components/schemas/v1DeleteObjectsResponseItem"
      description: Delete object response results, array format
    v1CopyObjectsRequestItem:
      type: object
      properties:
        srcPath:
          type: string
          title: Absolute path of the source object, including the file name. For example, foo/bar.jpg, foo/bar/baz.jpg, etc. Cannot contain characters other than [0-9, a-z, A-Z], /, !, -, _, ., , *, and Chinese characters
        dstPath:
          type: string
          title: Absolute path of the destination object, including the file name. For example, foo/bar.jpg, foo/bar/baz.jpg, etc. Cannot contain characters other than [0-9, a-z, A-Z], /, !, -, _, ., , *, and Chinese characters; the destination path must not be the same as the source path
        overwrite:
          type: boolean
          title: Whether to allow overwriting existing objects when the destination object already exists, default is true
          default: true
        removeOriginal:
          type: boolean
          title: Whether to delete the original object after copying, default is false
          default: false
      required:
        - srcPath
        - dstPath
    v1CopyObjectsRequestData:
      example:
        [
          {
            srcPath: "image.jpg",
            dstPath: "folder/image.jpg",
            removeOriginal: true,
          },
        ]
      type: array
      items:
        $ref: "#/components/schemas/v1CopyObjectsRequestItem"
      description: Batch copy object request parameters, array format
    v1CopyObjectsResponseItemError:
      type: object
      example:
        { "code": "OBJECT_NOT_EXIST", "message": "Storage object not exists." }
      properties:
        code:
          type: string
          title: Error code returned when the request for this object fails
        message:
          type: string
          title: Error description returned when the request for this object fails
    v1CopyObjectsResponseItemSuccess:
      type: object
      example: { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" }
      properties:
        cloudObjectId:
          type: string
          title: Cloud file ID after copying
    v1CopyObjectsResponseItem:
      type: object
      oneOf:
        - $ref: "#/components/schemas/v1CopyObjectsResponseItemSuccess"
        - $ref: "#/components/schemas/v1CopyObjectsResponseItemError"
    v1CopyObjectsResponseData:
      example:
        [
          {
            "code": "OBJECT_NOT_EXIST",
            "message": "Storage object not exists.",
          },
          { "cloudObjectId": "cloud://your-envId.bucket/file.jpg" },
        ]
      type: array
      items:
        $ref: "#/components/schemas/v1CopyObjectsResponseItem"

    CommonErrorResponse:
      type: object
      properties:
        code:
          type: string
          title: Error code
        message:
          type: string
          title: Error message
        requestId:
          type: string
          title: Request ID
      description: Error information returned when an error occurs
  securitySchemes:
    JWTAuth:
      type: http
      scheme: Bearer
      description: Token corresponding to the environment ID, obtained using login authentication (v2)
    APIKey:
      type: apiKey
      in: header
      name: Authorization
      description: Tencent Cloud 3.0 signature starting with TC3-HMAC-SHA256, with Timestamp and Token appended at the end of the signature

security:
  - JWTAuth: []
  - APIKey: []

tags:
  - name: 云存储对象操作