openapi: 3.0.3 info: title: Cloud Storage and Collaboration API version: v1 servers: - url: https://cloudstorage.adobe.io/v1 description: Production Server x-audience: prod security: - X-Api-Key: [] - AccessToken: [] tags: - name: Projects x-displayName: Projects description: | Projects are durable spaces used by teams to organize and collaborate on cloud documents and related cloud content. Along with serving as a collection, they can be used to point to a particular asset. Operations include: - name: Folders x-displayName: Folders description: | A construct that can contain assets and other folders, enabling logical organization of assets. Operations include: - Set Permissions for a folder - name: Files x-displayName: Files description: | Assets typically created through non-Adobe applications. The MIME type indicates the asset type. Operations include: - Modify file by ID (upload and or metadata) - name: Jobs x-displayName: Jobs Operations description: | This endpoint manages asynchronous jobs in the system. - name: PolicyOperations x-displayName: Policy Operations description: | This endpoint manages policies in the system. paths: /projects: get: operationId: getProjects summary: Get Paginated List of Projects tags: - Projects description: | This endpoint returns a paginated list of all Projects within the organization's ESM shared storage that the requester is authorized to access. --- > NOTE: > * Includes only **CC Projects**. > * List does not include **discarded** projects. > * The response supports **cursor-based pagination** and includes a `nextUrl` field when additional pages are available. > * If there are no further results, the `nextUrl` field is omitted. > * Each item in the response provides **basic metadata** about the project. --- parameters: - $ref: "#/components/parameters/limit" - $ref: "#/components/parameters/cursor" - $ref: "#/components/parameters/projectsSortBy" - $ref: "#/components/parameters/projectsFilter" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/paginatedProjectsResponse" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidLimitType: $ref: "#/components/examples/invalidLimitType" invalidLimitRange: $ref: "#/components/examples/invalidLimitRange" invalidPaginationParameterCombination: $ref: "#/components/examples/invalidPaginationParameterCombination" multipleInvalidRequestViolations: $ref: "#/components/examples/multipleInvalidRequestViolations" "401": $ref: "#/components/responses/unauthorizedResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" post: operationId: createProject summary: Create a new project. parameters: - $ref: "#/components/parameters/requestId" tags: - Projects description: | This endpoint creates a new CC Project within the organization's ESM shared storage, provided the user has the necessary permissions. requestBody: $ref: "#/components/requestBodies/projectCreateRequest" responses: "201": description: | **Created** - The project was created successfully. headers: location: $ref: "#/components/headers/location" etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: createProject: $ref: "#/components/examples/singleProject" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequestBody: $ref: "#/components/examples/missingRequestBody" invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorProjectCreateResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequiredField: $ref: "#/components/examples/missingRequiredField" invalidName: $ref: "#/components/examples/invalidName" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}: get: operationId: getProject summary: Get a project by ID description: | This endpoint retrieves full metadata for a specific Project identified by its assetId. This includes project attributes such as name, type, creation details, and permissions. --- > NOTE: > * The project must exist and the requester must have at least read-level access. > * If the project is not found or access is denied, appropriate error responses will be returned. > * Discarded projects can be retrieved using this endpoint. > * If the project exists, but the requester does not have the requisite permissions: > - The API will behave as if the project does not exist. > - It will return a 404 Not Found response, even though the asset technically exists in the system. --- tags: - Projects parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/ifNoneMatch" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved information about the project headers: etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: projectById: $ref: "#/components/examples/singleProject" "304": $ref: "#/components/responses/matchedEtagResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/discard: post: operationId: discardProject summary: Discard a project by ID tags: - Projects description: | This endpoint marks an existing CC Project, identified by its `assetId`, for discard (soft deletion) along with all its descendant assets, from the organization’s ESM shared storage. This operation is allowed only if the requester has sufficient permissions to perform destructive actions on the project. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/ifMatch" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - The project was discarded successfully headers: etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: Discarded Project: $ref: "#/components/examples/200.projectDiscard" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "412": $ref: "#/components/responses/preconditionFailedResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/children: get: operationId: getProjectChildren summary: Get Paginated List of Children inside a Project tags: - Projects description: | This endpoint retrieves a paginated list of top-level assets (folders, files, or other resources) contained within a specified project, identified by its `assetId`. This allows clients to explore the immediate children of the project, supporting use cases like project browsing and navigation. The response includes all assets that the requester is authorized to view — regardless of asset type — excluding any that are hidden or discarded. Each item in the list contains basic metadata about the asset such as name, type, path, and identifiers. --- > NOTE: > * The response supports **cursor-based pagination** and includes a `nextUrl` field when additional pages are available. > * If there are no further results, the `nextUrl` field is omitted. > * The requester must have at least read-level access to the project. > * Assets are returned with basic metadata such as name, type, and hierarchy position. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/limit" - $ref: "#/components/parameters/cursor" - $ref: "#/components/parameters/assetsSortBy" - $ref: "#/components/parameters/assetsFilter" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/paginatedAssetsResponse" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidLimitType: $ref: "#/components/examples/invalidLimitType" invalidLimitRange: $ref: "#/components/examples/invalidLimitRange" invalidPaginationParameterCombination: $ref: "#/components/examples/invalidPaginationParameterCombination" multipleInvalidRequestViolations: $ref: "#/components/examples/multipleInvalidRequestViolations" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/effective-permission: get: operationId: getProjectEffectivePermission summary: Get User's Effective Permissions for a Project tags: - Projects description: | The endpoint retrieves the **effective permission (role)** assigned to the user for a specific project, identified by its `assetId`. It evaluates the users access based on: * **Direct permissions** assigned to the project. * **Predefined principals**, such as `_everybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/assetPermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/permissions: get: operationId: getProjectPermissions summary: Get All permissions for a Project tags: - Projects description: | The endpoint retrieves the **explicit roles and permissions** assigned to all users and groups for a specific project, identified by its `assetId` . This includes only the **direct access control entries** defined on the project itself and does not include any permissions that are inherited from parent folders or collections. --- > NOTE: > * The response lists all users and groups that have direct access to the project, along with their respective > roles (e.g., comment, edit). > * This data is useful for auditing and permission management but does not represent the full effective access > unless inheritance is also considered. > * The project must exist and the requester must have at least read-level access. If the project is not found or > access is denied, appropriate error responses will be returned. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/200.getAssetPermissions" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" patch: operationId: patchProjectPermissions summary: Patch Permissions for a Project tags: - Projects description: | This endpoint is used to manage the direct permissions of a specific project, identified by its `assetId`. It allows clients to perform multiple types of permission changes in a single request, including: * Addition of new users or groups to the access control list. * Update of roles for existing users or groups. * Removal of users or groups from the access control list. --- > NOTE: > * The request body supports three arrays: `additions`, `updates`, and `deletions`. > * Multiple principals can be included across each action type. > * Each principal must be mentioned only once across the entire request body. > * Permission changes are deeply inherited — they apply to the project and all of its descendant assets. > ## Validation Rules > | Action | Behavior | > | ------ | -------- | > | additions | Must include users/groups that **do not already exist** in the current ACL. | > | updates | Must target users/groups that **already exist** in the current ACL. | > | deletions | Must target users/groups that **already exist** in the current ACL. | --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/patchAssetPermissions" responses: "200": $ref: "#/components/responses/200.patchAssetPermissions" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequestBody: $ref: "#/components/examples/missingRequestBody" invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequiredField: $ref: "#/components/examples/missingRequiredField" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/package: post: operationId: packageProject summary: Package a Project tags: - Projects description: | This endpoint packages a project, identified by its `assetId`, into a downloadable format. The packaging process initiates an asynchronous job that prepares the project for export, creating one or multiple ZIP files that contains all assets and metadata associated with the project. In case of asynchronous operation succeed, the assets field will contain the list of file assets as defined by File Schema. Each file item in the list contains basic metadata about the file such as name, mediaType, path, and identifiers. The requester can then download each file individually. --- > NOTE: > * The request must include the `assetId` of the project to be packaged. > * The requester must have at least read-level access to the project. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/packageAssetResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /folders: post: operationId: createFolder summary: Create a new folder. parameters: - $ref: "#/components/parameters/requestId" tags: - Folders description: | This endpoint creates a folder or folder hierarchy under a specified parent container, which may be a Project or another Folder. The client must supply either a `name` (for single folder creation) or a `path` (for hierarchy creation). requestBody: $ref: "#/components/requestBodies/folderCreateRequest" responses: "201": description: | **Created** - The folder was created successfully. headers: location: $ref: "#/components/headers/location" etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/folderAsset" examples: createFolder: $ref: "#/components/examples/singleFolder" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequestBody: $ref: "#/components/examples/missingRequestBody" invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorFolderCreateResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequiredField: $ref: "#/components/examples/missingRequiredField" invalidName: $ref: "#/components/examples/invalidName" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /folders/{assetId}: get: operationId: getFolder summary: Get a folder by ID description: | This endpoint retrieves full metadata for a specific Folder identified by its assetId. This includes folder attributes such as name, type, creation details, and permissions. --- > NOTE: > * The folder must exist and the requester must have at least read-level access. > * If the folder is not found or access is denied, appropriate error responses will be returned. > * Discarded folders can be retrieved using this endpoint. > * If the folder exists, but the requester does not have the requisite permissions: > - The API will behave as if the folder does not exist. > - It will return a 404 Not Found response, even though the asset technically exists in the system. --- tags: - Folders parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/ifNoneMatch" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved information about the folder headers: etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/folderAsset" examples: folderById: $ref: "#/components/examples/singleFolder" "304": $ref: "#/components/responses/matchedEtagResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /folders/{assetId}/children: get: operationId: getFolderChildren summary: Get Paginated List of Children inside a Folder tags: - Folders description: | This endpoint retrieves a paginated list of top-level assets (folders, files, or other resources) contained within a specified folder, identified by its `assetId`. This allows clients to explore the immediate children of the folder, supporting use cases like folder browsing and navigation. The response includes all assets that the requester is authorized to view — regardless of asset type — excluding any that are hidden or discarded. Each item in the list contains basic metadata about the asset such as name, type, path, and identifiers. --- > NOTE: > * The response supports **cursor-based pagination** and includes a `nextUrl` field when additional pages are available. > * If there are no further results, the `nextUrl` field is omitted. > * The requester must have at least read-level access to the folder. > * Assets are returned with basic metadata such as name, type, and hierarchy position. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/limit" - $ref: "#/components/parameters/cursor" - $ref: "#/components/parameters/assetsSortBy" - $ref: "#/components/parameters/assetsFilter" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/paginatedAssetsResponse" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidLimitType: $ref: "#/components/examples/invalidLimitType" invalidLimitRange: $ref: "#/components/examples/invalidLimitRange" invalidPaginationParameterCombination: $ref: "#/components/examples/invalidPaginationParameterCombination" multipleInvalidRequestViolations: $ref: "#/components/examples/multipleInvalidRequestViolations" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /folders/{assetId}/effective-permission: get: operationId: getFolderEffectivePermission summary: Get User's Effective Permissions for a Folder tags: - Folders description: | The endpoint retrieves the **effective permission (role)** assigned to the user for a specific folder, identified by its `assetId`. It evaluates the users access based on: * **Direct permissions** assigned to the folder. * **Inherited permissions** from ancestor folders or the containing project. * **Predefined principals**, such as `_everybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/assetPermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}: get: operationId: getFile summary: Get a file by ID description: | This endpoint retrieves full metadata for a specific File identified by its assetId. This includes file attributes such as name, type, creation details, and permissions. --- > NOTE: > * The file must exist and the requester must have at least read-level access. > * If the file is not found or access is denied, appropriate error responses will be returned. > * Discarded files can be retrieved using this endpoint. > * If the file exists, but the requester does not have the requisite permissions: > - The API will behave as if the file does not exist. > - It will return a 404 Not Found response, even though the asset technically exists in the system. --- tags: - Files parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/ifNoneMatch" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved information about the file headers: etag: $ref: "#/components/headers/etag" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/fileAsset" examples: fileById: $ref: "#/components/examples/singleFile" "304": $ref: "#/components/responses/matchedEtagResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/effective-permission: get: operationId: getFileEffectivePermission summary: Get User's Effective Permissions for a File tags: - Files description: | The endpoint retrieves the **effective permission (role)** assigned to the user for a specific file, identified by its `assetId`. It evaluates the users access based on: * **Direct permissions** assigned to the file. * **Inherited permissions** from ancestor folders or the containing project. * **Predefined principals**, such as `_everybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/assetPermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/download: get: operationId: downloadFile summary: Range Based Download of a file through a Pre-signed URL tags: - Files description: | This endpoint returns metadata and pre-signed URLs that can be used to download large files in chunks using range-based access. The response includes the following: - The pre-signed URL that supports HTTP range requests for partial downloads - The expiration date of the pre-signed URL - The size of the file in bytes - The MIME type of the file --- > NOTE: > * The pre-signed URL is valid for a limited time and must be used within that timeframe. > * The requester must have at least read-level access to the file. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/urlTTL" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/fileDownloadUrlResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/image-rendition: get: operationId: getFileImageRendition summary: Get an image rendition of a file by ID description: | This endpoint returns an image rendition of the specified file, suitable for display in previews, thumbnails, or alternate resolution downloads. --- > NOTE: > * The file must exist and the requester must have at least read-level access. > * If the file is not found or access is denied, appropriate error responses will be returned. > * Image renditions of discarded files can be retrieved using this endpoint. > * If the file exists, but the requester does not have the requisite permissions: > - The API will behave as if the file does not exist. > - It will return a 404 Not Found response, even though the asset technically exists in the system. --- tags: - Files parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/ifMatch" - $ref: "#/components/parameters/ifNoneMatch" - $ref: "#/components/parameters/requestId" - $ref: "#/components/parameters/size" - $ref: "#/components/parameters/mediaType" responses: "200": description: | **Success** - Retrieved image rendition of the file headers: x-request-id: $ref: "#/components/headers/requestId" content: image/*: schema: type: string format: binary "304": $ref: "#/components/responses/matchedEtagResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "412": $ref: "#/components/responses/preconditionFailedResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/upload/init: post: operationId: initBlockBasedFileUpload summary: Initialize a block based file upload job description: | This, along with the set of related APIs enables the upload of large files by splitting the content into multiple blocks, transferred over separate requests. This method is ideal for files larger than 10 MB, offering parallelism, resumability, and efficient error recovery. ## Upload Flow Overview ### 1. Initiate Upload: Client sends a POST request to initiate the block upload and receives a response with URLs for uploading individual blocks and finalizing the transfer. ### 2. Upload Blocks: Client issues PUT requests to the provided Block Transfer URLs, sending file data in chunks. These can be uploaded in parallel. --- > NOTE: > #### Uploading File Blocks > After receiving `transferLinks`, clients can use them to upload individual blocks: > **PUT ** > **** > > * **Authorization Header**: Must NOT be included in the request. > * **Success Response**: 200 OK indicates successful block upload. > * **Expiration Handling**: Each upload session is time-bound. If blocks are not uploaded within the specified expiration window > (urlExpirationDate field from the initiation response), the operation may fail. > - **Always check and respect the urlExpirationDate timestamp** in the response from the Block Upload Init endpoint. --- ### 3. Finalize Upload: After all blocks are uploaded, the client calls the [Block Finalize URL](#/Files/finalizeBlockBasedFileUpload) to trigger the upload to the destination location. ### 4. Monitor: Finalize operation's response includes a Monitor URL to check the final status. # Initialize the Block-Based Upload This endpoint allows clients to initiate the creation of a new file using block-based transfer. --- > NOTE: > The expiration duration of transfer URLs is explicitly provided to the client in the response --- tags: - Files parameters: - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/fileUploadInitRequest" responses: "200": $ref: "#/components/responses/fileUploadInitResponse" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequestBody: $ref: "#/components/examples/missingRequestBody" invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequiredField: $ref: "#/components/examples/missingRequiredField" invalidName: $ref: "#/components/examples/invalidName" ancestorNotFound: $ref: "#/components/examples/ancestorNotFound" invalidDestination: $ref: "#/components/examples/invalidDestination" invalidSize: $ref: "#/components/examples/invalidSize" unsupportedMediaType: $ref: "#/components/examples/unsupportedMediaType" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/upload/finalize: post: operationId: finalizeBlockBasedFileUpload summary: Finalize a block based file upload job description: | This endpoint finalizes the block upload process by initiating an asynchronous job that will merge all uploaded blocks and creates the final file asset. In case of asynchronous operation succeed, the asset field will contain the newly created file's metadata as defined by File Schema. --- > NOTE: > ### Validation and Behavior for Finalize (Block-Based Upload) > The following rules govern how the server interprets the finalization request for a block-based upload: > > #### File Size in Initialization > * The size provided during the initiate request is treated as an estimate, not a strict validation boundary. > * Clients are not penalized if the actual uploaded content size differs from the declared size. > * In future, clients will be able to extend block sets if their initial estimate is too low (see Future Enhancements). > #### Skipped Blocks > * Clients are allowed to skip any block from the original transferLinks list, as long as part numbers remain ordered and are accurately reported in the `usedTransferLinks` array during finalize. > * Skipped parts should simply be omitted from `usedTransferLinks`. > #### Finalization is based on: > * The used part numbers explicitly listed in the `usedTransferLinks` array. > * The server will stitch together content in the order of these part numbers. > * Any parts not listed will be ignored even if data was uploaded to them. --- tags: - Files parameters: - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/fileUploadFinalizeRequest" responses: "202": $ref: "#/components/responses/fileUploadFinalizeResponse" "400": description: | **Invalid Request** - The server cannot process the request due to a client error headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequestBody: $ref: "#/components/examples/missingRequestBody" invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: missingRequiredField: $ref: "#/components/examples/missingRequiredField" invalidName: $ref: "#/components/examples/invalidName" ancestorNotFound: $ref: "#/components/examples/ancestorNotFound" invalidDestination: $ref: "#/components/examples/invalidDestination" invalidSize: $ref: "#/components/examples/invalidSize" unsupportedMediaType: $ref: "#/components/examples/unsupportedMediaType" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /status/{jobId}: get: operationId: getJobStatus summary: Get the status of an asynchronous job description: | This endpoint retrieves the current status of an asynchronous job identified by its jobId. --- > NOTE: > * The job must exist. > * If the job is not found, appropriate error responses will be returned. > * The job status is updated periodically, and the client should poll this endpoint to get the latest status, based on the retry-after header. --- tags: - Jobs parameters: - name: jobId in: path required: true schema: $ref: "#/components/schemas/jobId" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - The status of the asynchronous job headers: retry-after: $ref: "#/components/headers/retryAfter" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/jobStatus" "401": $ref: "#/components/responses/unauthorizedResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" components: securitySchemes: Authorization: type: http scheme: bearer bearerFormat: JWT description: IMS User Token or Service 2 Service (Technical Account). Required for all API endpoints. Must be a valid JWT token. schemas: errorCodeEnums: type: string title: ErrorCodeEnums description: | It describes the type of error through a human readable code. enum: - invalid_request - unauthorized - access_error - resource_not_found - invalid_operation - cursor_expired - precondition_failed - etag_mismatch - invalid_content_type - validation_error - rate_limited - runtime_error - not_implemented - storage_quota_exceeded assetTypeEnums: type: string title: AssetType description: | Describes the type of asset. enum: - folder - file - project - library - cloudDoc patchPermissionResultEnums: type: string title: PatchPermissionResultEnums description: | Describes the result of the permission patch for each principal. enum: - successful - failed - pending jobTypeEnums: type: string title: JobTypeEnums description: | It describes the type of asynchronous job, depends on the original API invocation that created the job. enum: - file_upload - copy_asset - move_asset - package_asset jobStatusEnums: type: string title: JobStatusEnums description: | It describes the status of an asynchronous job. enum: - running - succeeded - failed - partially_succeeded asset: description: | Represents a generic asset in the system. required: - assetType oneOf: - $ref: "#/components/schemas/fileAsset" - $ref: "#/components/schemas/folderAsset" - $ref: "#/components/schemas/projectAsset" discriminator: propertyName: assetType mapping: file: "#/components/schemas/fileAsset" folder: "#/components/schemas/folderAsset" project: "#/components/schemas/projectAsset" pagination: type: object title: Pagination description: Pagination information for collection responses properties: nextUrl: type: string description: URI to the next page of results format: uri limit: type: integer description: Maximum number of items per page format: int32 required: - limit example: limit: 10 nextUrl: https://api.example.com/assets?cursor=550e8400-e29b-41d4-a716-446655440000&limit=10 assetId: type: string title: Asset Id description: A globally unique identifier for the asset example: urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 date: type: string format: date-time example: "2021-01-01T00:00:00Z" principalId: type: string description: The Unique ID for the principal in the system example: 08D81E3B665BE5640A495C2C@AdobeOrg path: title: Path description: The path of the asset from the parent collection. type: string example: /My Project/My Folder/My Asset ancestors: type: array description: | Ordered list of ancestor asset IDs (first is immediate parent). items: $ref: "#/components/schemas/assetId" example: - urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 - urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a175 - urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a176 baseAsset: type: object title: BaseAsset description: | Contains the common properties for all assets in the system. --- > NOTE: > It is not intended to be used directly --- required: - name - assetId properties: assetId: allOf: - $ref: "#/components/schemas/assetId" readOnly: true name: type: string description: Human-readable name of the asset example: My Asset createdDate: allOf: - $ref: "#/components/schemas/date" description: Timestamp when the asset was created readOnly: true modifiedDate: allOf: - $ref: "#/components/schemas/date" description: Timestamp of the most recent update readOnly: true createdBy: allOf: - $ref: "#/components/schemas/principalId" description: IMS user ID of the principal who created the asset readOnly: true example: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: allOf: - $ref: "#/components/schemas/principalId" description: IMS user ID of the principal who last modified the asset readOnly: true example: 08D81E3B665BE5640A495C2C@AdobeOrg path: allOf: - $ref: "#/components/schemas/path" readOnly: true ancestors: allOf: - $ref: "#/components/schemas/ancestors" readOnly: true state: type: string description: Current state of the asset enum: - active - discarded - discarded_parent default: active projectAsset: type: object title: ProjectAsset description: Represents a project in the system allOf: - $ref: "#/components/schemas/baseAsset" - type: object properties: assetType: type: string default: project required: - assetType paginatedProjects: title: PaginatedProjects description: Represents a paginated list of projects type: object properties: paging: $ref: "#/components/schemas/pagination" items: type: array items: $ref: "#/components/schemas/projectAsset" errorResponse: type: object title: ErrorResponse description: | Describes an error that occurred while processing a request. required: - error_code - message properties: error_code: $ref: "#/components/schemas/errorCodeEnums" readOnly: true message: type: string description: A human-readable explanation specific to this occurrence of the problem. readOnly: true requestId: type: string description: A unique identifier for the request that caused the error. readOnly: true additionalProperties: true assetName: type: string description: The name of the asset (including the extension, in case of a file) minLength: 1 maxLength: 255 nullable: false etag: type: string description: Entity tag used for optimistic concurrency control example: 33a64df551425fcc55e4d42a148795d9f25f89d4 fileAsset: type: object title: FileAsset description: Represents a file in the system allOf: - $ref: "#/components/schemas/baseAsset" - type: object properties: assetType: type: string default: file mediaType: type: string description: The MIME type of the file example: image/jpeg size: type: integer description: Size of the file in bytes format: int64 minimum: 0 example: 1048576 contentEtag: allOf: - $ref: "#/components/schemas/etag" description: ETag of the file content's required: - assetType - mediaType - size - contentEtag folderAsset: type: object title: FolderAsset description: Represents a folder in the system allOf: - $ref: "#/components/schemas/baseAsset" - type: object properties: assetType: type: string default: folder required: - assetType paginatedAssets: title: PaginatedAssets description: Represents a paginated list of assets type: object properties: paging: $ref: "#/components/schemas/pagination" children: type: array items: $ref: "#/components/schemas/asset" roleEnums: type: string title: RoleEnums description: | It describes the level of access granted for an asset to a subject. Following roles are supported: - `edit` - The subject has edit access to the asset. It includes all permissions of the `comment` role as well as the ability to share the asset with other users. - `comment` - The subject has comment access to the asset. It includes the ability to view the asset and add comments to it. enum: - edit - comment example: edit baseDirectPermissionEntry: type: object title: BaseDirectPermissionEntry properties: id: $ref: "#/components/schemas/principalId" name: type: string title: Name description: Display name of the principal. role: $ref: "#/components/schemas/roleEnums" required: - id - name - role userDirectPermissionEntry: type: object title: UserDirectPermissionEntry allOf: - $ref: "#/components/schemas/baseDirectPermissionEntry" - type: object properties: type: type: string default: user email: type: string format: email description: Email of the user. required: - type - email groupDirectPermissionEntry: type: object title: GroupDirectPermissionEntry allOf: - $ref: "#/components/schemas/baseDirectPermissionEntry" - type: object properties: type: type: string default: group organizationName: type: string description: Name of the organization. required: - type - organizationName predefinedGroupsDirectPermissionEntry: type: object title: PredefinedGroupsDirectPermissionEntry allOf: - $ref: "#/components/schemas/baseDirectPermissionEntry" - type: object properties: type: type: string default: predefined organizationName: type: string description: Name of the organization. required: - type - organizationName directPermissionEntry: type: object title: DirectPermissionEntry description: Represents a principal (user, group, or predefined groups) with associated role. oneOf: - $ref: "#/components/schemas/userDirectPermissionEntry" - $ref: "#/components/schemas/groupDirectPermissionEntry" - $ref: "#/components/schemas/predefinedGroupsDirectPermissionEntry" discriminator: propertyName: type mapping: user: "#/components/schemas/userDirectPermissionEntry" group: "#/components/schemas/groupDirectPermissionEntry" predefined: "#/components/schemas/predefinedGroupsDirectPermissionEntry" pendingPermissionEntry: type: object title: PendingPermissionEntry description: Represents a pending permission entry for a user along with the role and the timestamp of the invitation. properties: email: type: string format: email title: Invited Email description: Email address of the invited user. role: $ref: "#/components/schemas/roleEnums" created: allOf: - $ref: "#/components/schemas/date" description: Timestamp when the invitation was created. id: type: string title: Invitation ID description: Unique identifier for the invitation (typically mailto:). required: - email - role - created - id assetPermissionsResponse: type: object title: AssetPermissionsResponse properties: direct: type: array title: Direct Permissions items: $ref: "#/components/schemas/directPermissionEntry" default: [] pending: type: array title: Pending Invitations items: $ref: "#/components/schemas/pendingPermissionEntry" default: [] principalTypeEnums: description: | Represents all the types of principals type: string enum: - user - group - predefined patchAssetPermissionsRequest: type: object title: PatchAssetPermissionsRequest description: Represents the request body for a patch operation on permissions for an asset properties: direct: type: object title: DirectPermissionsModification properties: additions: type: array title: AdditionsList description: Represents a list of users or groups that are being granted permission for an asset items: description: Represents a user or group that is being granted permission for an asset type: object title: NewPermissionEntry properties: recipient: type: string description: | Provides identifier for the recipient. It can be one of the following formats: | Type of Recipient | Format | Description | Example | | ----------------- | ------ | ----------- | ------- | | User | mailto: | Group name defined in the organization | name:Example Group | | Predefined | name: | Predefined principal name | name:_everybody | type: $ref: "#/components/schemas/principalTypeEnums" role: $ref: "#/components/schemas/roleEnums" required: - recipient - type - role maxItems: 10 default: [] updates: type: array title: UpdatesList description: Represents a list of users or groups with a new role items: description: Represents a user or group with a new role type: object title: UpdatedPermissionEntry properties: id: $ref: "#/components/schemas/principalId" type: $ref: "#/components/schemas/principalTypeEnums" role: $ref: "#/components/schemas/roleEnums" required: - id - type - role maxItems: 10 default: [] deletions: type: array title: DeletionsList description: Represents a list of users or groups that are being removed from the asset items: description: Represents a user or group that is being removed from the asset type: object title: DeletionPermissionEntry properties: id: $ref: "#/components/schemas/principalId" type: $ref: "#/components/schemas/principalTypeEnums" maxItems: 10 default: [] required: - direct basePatchPermissionEntry: type: object title: BasePatchPermissionEntry description: Represents a base permission entry properties: id: $ref: "#/components/schemas/principalId" type: $ref: "#/components/schemas/principalTypeEnums" required: - id - type successfulPatchPermissionEntry: description: Represents a successful permission entry title: SuccessfulPatchPermissionEntry type: object allOf: - $ref: "#/components/schemas/basePatchPermissionEntry" - type: object properties: status: type: string default: successful role: $ref: "#/components/schemas/roleEnums" required: - status failedPatchPermissionEntry: description: Represents a failed permission entry title: FailedPatchPermissionEntry type: object allOf: - $ref: "#/components/schemas/basePatchPermissionEntry" - type: object properties: status: type: string default: failed error_code: type: string message: type: string role: $ref: "#/components/schemas/roleEnums" additionalProperties: true required: - status - error_code - message pendingPatchPermissionEntry: description: Represents a pending permission entry title: PendingPatchPermissionEntry type: object allOf: - $ref: "#/components/schemas/basePatchPermissionEntry" - type: object properties: status: type: string default: pending created: $ref: "#/components/schemas/date" email: type: string format: email description: Email of the user. role: $ref: "#/components/schemas/roleEnums" required: - status - email - role - created patchPermissionResultEntry: description: | Represents a permission patch result entry. title: PatchPermissionResultEntry required: - status oneOf: - $ref: "#/components/schemas/successfulPatchPermissionEntry" - $ref: "#/components/schemas/failedPatchPermissionEntry" - $ref: "#/components/schemas/pendingPatchPermissionEntry" discriminator: propertyName: status mapping: successful: "#/components/schemas/successfulPatchPermissionEntry" failed: "#/components/schemas/failedPatchPermissionEntry" pending: "#/components/schemas/pendingPatchPermissionEntry" patchAssetPermissionsResponse: type: object title: PatchAssetPermissionsResponse properties: direct: title: PatchAssetDirectPermissionsResult type: object properties: additions: type: array title: AdditionsList description: Status of each permission addition. items: $ref: "#/components/schemas/patchPermissionResultEntry" default: [] updates: type: array title: UpdatesList description: Status of each permission update. items: $ref: "#/components/schemas/patchPermissionResultEntry" default: [] deletions: type: array title: DeletionsList description: Status of each permission deletion. items: $ref: "#/components/schemas/patchPermissionResultEntry" default: [] required: - direct url: type: string title: URL description: A URL for the asset format: uri fileSize: type: integer title: FileSize description: The size of the file in bytes. minimum: 1 format: int64 example: 1048576 jobId: type: string title: JobId description: A globally unique identifier for the asynchronous job requestId: type: string title: RequestId description: An identifier provided by the client to identify the request. example: "1234567890" minLength: 1 maxLength: 128 baseJobStatus: type: object title: BaseJobStatus description: | Contains the common properties for all asynchronous jobs in the system. --- > NOTE: > It is not intended to be used directly --- required: - jobId - requestId - jobType properties: jobId: $ref: "#/components/schemas/jobId" requestId: $ref: "#/components/schemas/requestId" jobType: type: string description: | The type of the asynchronous job, depends on the original API invocation that created the job. Currently, the following job types are supported: - file_upload - copy_asset - move_asset - package_asset runningJobStatus: type: object title: RunningJobStatus description: Represents the status of a running asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: running required: - status fileUploadSucceededJobStatus: type: object title: FileUploadSucceededJobStatus description: Represents the status of a file upload succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded asset: $ref: "#/components/schemas/asset" required: - asset - status packageAssetSucceededJobStatus: type: object title: PackageAssetSucceededJobStatus description: Represents the status of a package asset succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded assets: type: array items: $ref: "#/components/schemas/asset" required: - assets - status succeededJobStatus: description: | Represents the status of a succeeded asynchronous job in the system required: - jobType oneOf: - $ref: "#/components/schemas/fileUploadSucceededJobStatus" - $ref: "#/components/schemas/packageAssetSucceededJobStatus" discriminator: propertyName: jobType mapping: file_upload: "#/components/schemas/fileUploadSucceededJobStatus" package_asset: "#/components/schemas/packageAssetSucceededJobStatus" failedJobStatus: type: object title: FailedJobStatus description: Represents the status of a failed asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: failed errors: type: array description: The errors that occurred during the job items: $ref: "#/components/schemas/errorResponse" required: - status - errors jobStatus: title: JobStatus description: Represents the status of a job in the system. required: - status oneOf: - $ref: "#/components/schemas/runningJobStatus" - $ref: "#/components/schemas/succeededJobStatus" - $ref: "#/components/schemas/failedJobStatus" discriminator: propertyName: status mapping: running: "#/components/schemas/runningJobStatus" succeeded: "#/components/schemas/succeededJobStatus" failed: "#/components/schemas/failedJobStatus" parameters: limit: name: limit in: query required: false description: | * Provides a hint for the number of items per page. * In cases where multiple elements have the same field value used to split the page, the server may adjust the number of items returned to ensure page boundaries align correctly. schema: type: integer minimum: 1 default: 20 maximum: 100 cursor: name: cursor in: query required: false description: | Cursor used for fetching next set of results. * If not provided, the first page of results is returned. * For subsequent pages, only the cursor should be sent. --- > NOTE: > The cursor is opaque and should not be parsed or modified by clients. --- schema: type: string example: 123e4567e89b12d3a456426614174000 projectsSortBy: name: sortBy in: query required: false description: | Defines the sort order. * If not specified, the **default is `+name`**. * Prefix with `-` for descending order. `+` is optional for ascending order. Following fields are supported for sorting: - name - created --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string example: created projectsFilter: name: filter in: query required: false description: | [FIQL-based](https://datatracker.ietf.org/doc/html/draft-nottingham-atompub-fiql-00) filter string Following fields are supported for filtering: - `view`: Filters the results to only a specific view. The possible values are `yours`, `all`, `shared_with_you`, `discoverable`. Here is how each view works: - `Yours`: - Projects in the calling user's User Home storage - Projects in the calling user's Org's ESM shared storage for which the user has access, excluding those which they only have read permissions through membership in the org_everybody group. - `Shared with you`: - Projects in other user's User Home storage for which the calling user has permissions - Projects in other Org's ESM shared storage for which the calling user has permissions - `All`: - Combination of Projects returned from `Yours` and `Shared with you` --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string example: view==discoverable requestId: name: x-request-id in: header schema: type: string example: 1234567890 minLength: 1 maxLength: 128 description: | The `X-Request-Id` header is used to identify a request. It can be used to correlate logs and other resources and is intended to be a non-persistent identifier. assetId: name: assetId in: path required: true description: | The ID of the asset to get. schema: $ref: "#/components/schemas/assetId" ifNoneMatch: name: If-None-Match in: header schema: type: string example: \"33a64df551425fcc55e4d42a148795d9f25f89d4\", W/\"0815\" required: false description: | One or more ETag values to compare, separated by commas. The request will succeed only if the resource's current ETag does **not** match any of the provided values. This allows clients to avoid unnecessary data transfer if the resource has not changed since their last fetch. ifMatch: name: If-Match in: header schema: type: string example: \"33a64df551425fcc55e4d42a148795d9f25f89d4\", W/\"0815\" required: false description: | One or more ETag values to compare, separated by commas. The request will succeed only if the resource's current ETag matches any of the provided values. This allows clients to prevent resource conflicts when multiple clients try to update the same resource simultaneously. assetsSortBy: name: sortBy in: query required: false description: | Defines the sort order. * If not specified, the **default is `+name`**. * Prefix with `-` for descending order. `+` is optional for ascending order. Following fields are supported for sorting: - name - created - modified --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string example: "-modified,+name" assetsFilter: name: filter in: query required: false description: | [FIQL-based](https://datatracker.ietf.org/doc/html/draft-nottingham-atompub-fiql-00) filter string Following fields are supported for filtering: - `mediaType`: Filter by media type (operators allowed are ==). Multiple values can be provided by following the FIQL syntax. - `assetType`: Filter by asset type (operators allowed are ==). Multiple values can be provided by following the FIQL syntax. --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string example: assetType==file;mediaType==application/vnd.adobe.library+dcx;modified=gt=2025-01-01 urlTTL: name: urlTTL in: query required: false description: | * Provides a **client provided hint** for Time-To-Live(TTL) in seconds for the pre-signed download URL. --- > NOTE: > * Clients must rely on the `urlExpirationDate` field in the response for the actual expiration time. --- schema: type: integer default: 14400 minimum: 60 maximum: 14400 size: name: size in: query required: false description: | The desired dimension of the resulting rendition on the longest side, whether that is width or height. schema: type: integer mediaType: name: mediaType in: query required: false description: | The desired content type of the resulting rendition. schema: type: string default: image/png example: image/jpeg headers: requestId: schema: type: string example: 1234567890 minLength: 1 maxLength: 128 description: | The `X-Request-Id` header is used to identify a request. It can be used to correlate logs and other resources and is intended to be a non-persistent identifier. required: true retryAfter: required: true schema: type: integer format: int32 minimum: 0 example: 120 description: The number of seconds the user agent should wait to make a follow up request description: | The `Retry-After` header indicates how long the user agent should wait before making a follow-up request. The Retry-After value can be either an HTTP-date or a number of seconds to delay after receiving the response. For more details, please head over to [RFC9110](https://datatracker.ietf.org/doc/html/rfc9110#name-retry-after). location: required: true schema: type: string example: https://cloudstorage.adobe.io/v1/projects/1234567890 description: | The `Location` header indicates the URL to access the newly created asset. etag: required: true schema: type: string example: "1234567890" description: | The `ETag` header is used to identify a specific version of a resource. The ETag value can be used to make conditional requests to the server. examples: paginatedProjects: description: | **Get Projects** - The server successfully retrieved the projects value: paging: nextUrl: https://cloudstorage.adobe.io/v1/projects?cursor=eyJvZmZzZXQiOjN9 limit: 20 items: - assetType: project assetId: urn:aaid:sc:US:7eb8f0f0-dbe8-466d-9f74-84c653dfaf22 name: Marketing Launch Plan createdDate: "2024-04-15T10:20:30Z" modifiedDate: "2024-04-20T15:45:10Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /Marketing Launch Plan ancestors: [] state: active - assetType: project assetId: urn:aaid:sc:US:33132aca-7fef-4b28-93e9-b79dbf4c5f4f name: Brand Refresh createdDate: "2024-03-10T09:12:00Z" modifiedDate: "2024-04-01T08:50:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: A495C2C08D81E3B665BE5640@AdobeOrg path: /Brand Refresh ancestors: [] state: active - assetType: project assetId: f860f2fc-7942-4e49-ab37-5e2b32afe97a name: Holiday Campaign createdDate: "2024-01-05T14:00:00Z" modifiedDate: "2024-01-10T10:25:30Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /Holiday Campaign ancestors: [] state: active invalidLimitType: description: | **Mismatch Parameter Type** - Provided value of limit parameter is not compatible with the expected type value: error_code: invalid_request message: "Provided value: (abc) for query parameter: limit is of invalid type. Allowed Type is Integer" requestId: 123e4567-e89b-12d3-a456-426614174000 invalidLimitRange: description: | **Invalid Range** - Provided value of limit parameter is out of the allowed range value: error_code: invalid_request message: "Provided value: (1000) for query parameter: limit is out of the allowed range. Allowed Range is 1-100" requestId: 123e4567-e89b-12d3-a456-426614174000 invalidPaginationParameterCombination: description: | **Invalid Combination** - Combination of pagination parameters is invalid value: error_code: invalid_request message: "Following query parameters: [cursor and sortBy] are not allowed together" requestId: 123e4567-e89b-12d3-a456-426614174000 multipleInvalidRequestViolations: description: | **Multiple Violations** - Multiple problems with the request value: error_code: invalid_request message: Multiple issues with request, refer details array for more information details: - field: limit value: -2 allowedRange: "[1, 100]" message: Value is out of range location: query - field: x-request-id value: "" message: Invalid string length location: header allowedLength: "[1, 128]" - field: sortBy value: created message: Invalid value allowedValues: "[name, +name, -name, modified, +modified, -modified]" location: query - field: filter value: modified eq 2025 format: Feed Item Query Language(FIQL) message: Invalid format location: query - field: cursor incompatibleField: sortBy message: Invalid combination location: query - field: limit value: abc message: Invalid type allowedType: Integer location: query unauthorized: description: | **Unauthorized** - The request is unauthorized. value: error_code: unauthorized message: You are not authorized to access this resource. requestId: 123e4567-e89b-12d3-a456-426614174000 rateLimited: description: | **Rate Limited** - The server has rate limited the request value: error_code: rate_limited message: Too many requests have been made. Please try after specified time. requestId: 123e4567-e89b-12d3-a456-426614174000 runtimeError: description: | **Runtime Error** - An unexpected error occurred while processing the request value: error_code: runtime_error message: An unexpected error occurred while processing your request. requestId: 123e4567-e89b-12d3-a456-426614174000 singleProject: value: assetId: urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 name: My New Project createdDate: "2024-01-05T14:00:00Z" modifiedDate: "2024-01-10T10:25:30Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /My New Project ancestors: [] assetType: project state: active missingRequestBody: description: | **Missing Request Body** - The server cannot proceed because the request body is missing value: error_code: invalid_request message: The request is missing the required body requestId: 123e4567-e89b-12d3-a456-426614174000 invalidRequestBody: description: | **Invalid Request Body** - The server cannot proceed because the request body is not valid JSON value: error_code: invalid_request message: The provided request body is not a valid JSON requestId: 123e4567-e89b-12d3-a456-426614174000 accessErrorProjectCreate: description: | **Project Create Error** - Access to create a project is denied value: error_code: access_error message: You do not have permission to create projects. requestId: 123e4567-e89b-12d3-a456-426614174000 invalidContentType: description: | **Invalid Content Type** - The server does not support the provided content type value: error_code: invalid_content_type message: The request content type is not supported. requestId: 123e4567-e89b-12d3-a456-426614174000 missingRequiredField: description: | **Missing Required Field** - The server cannot proceed because the request body is missing a required field value: error_code: validation_error message: The request body is missing the required field (#name) requestId: 123e4567-e89b-12d3-a456-426614174000 invalidName: description: | **Invalid Name** - The server cannot proceed because the name is invalid value: error_code: validation_error message: The provided name has an invalid value. requestId: 123e4567-e89b-12d3-a456-426614174000 accessError: description: | **Access Error** - Access to a resource is denied value: error_code: access_error message: "You do not have following permission(s) to perform this action on the resource: [write, delete]." requestId: 123e4567-e89b-12d3-a456-426614174000 resourceNotFound: description: | **Resource Not Found** - The requested resource was not found value: error_code: resource_not_found message: The requested resource (urn:uuid:123e4567-e89b-12d3-a456-426614174000) was not found. requestId: 123e4567-e89b-12d3-a456-426614174000 200.projectDiscard: value: assetId: urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 name: My New Project createdDate: "2024-01-05T14:00:00Z" modifiedDate: "2024-01-10T10:25:30Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /My New Project ancestors: [] assetType: project state: discarded invalidOperation: description: | **Invalid Operation** - The requested operation is invalid based on the current state of the resource value: error_code: invalid_operation message: The requested operation (discard) is invalid based on the current state of the resource. requestId: 123e4567-e89b-12d3-a456-426614174000 etagMismatch: description: | **Precondition Failed** - The request failed due to a precondition value: error_code: etag_mismatch message: Expected etag is different for the current. requestId: 123e4567-e89b-12d3-a456-426614174000 paginatedAssets: description: | **Paginated Assets** - The server successfully retrieved the assets value: paging: nextUrl: https://cloudstorage.adobe.io/v1/projects/7eb8f0f0-dbe8-466d-9f74-84c653dfaf22/children?cursor=eyJvZmZzZXQiOjN9 limit: 20 children: - assetType: folder assetId: urn:aaid:sc:US:11111111-aaaa-bbbb-cccc-222222222222 name: Design Assets createdDate: "2024-03-01T10:00:00Z" modifiedDate: "2024-04-01T10:30:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /Marketing Launch Plan/Design Assets ancestors: - urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a etag: "1683839000001" state: active - assetType: file assetId: urn:aaid:sc:US:22222222-aaaa-bbbb-cccc-333333333333 name: logo.png createdDate: "2024-02-20T09:10:00Z" modifiedDate: "2024-03-05T11:20:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /Marketing Launch Plan/logo.png ancestors: - urn:aaid:sc:US:11111111-aaaa-bbbb-cccc-222222222222 contentEtag: "1683839000010" mediaType: image/png size: 2418293 state: active 200.assetPermissions: description: | **Asset Permissions** - The permissions for the asset value: direct: - id: 13A5316551352CF40A490D35@AdobeID type: user role: edit email: user01@adobetest.com name: test user - id: 11301C2F67F84EA80A494021@AdobeOrg:639451533 type: group role: comment name: test group organizationName: Test Org - id: orgEverybody type: predefined organizationName: Example Inc. name: _everybody role: comment pending: - email: john.doe@example.com role: edit created: "2021-01-01T00:00:00Z" id: mailto:john.doe@example.com patchAssetPermissions: description: | **Modify Asset Permissions** - The request body for a patch operation on permissions for an asset value: direct: additions: - recipient: name:Example Group type: group role: edit - recipient: mailto:john.doe@example.com type: user role: comment updates: - id: 13A5316551352CF40A490D35@AdobeID type: user role: edit - id: 11301C2F67F84EA80A494021@AdobeOrg:639451533 type: group role: edit deletions: - id: 13A5316551352CF40A490D37@AdobeID type: user - id: 11301C2F67F84EA80A494025@AdobeOrg:639451533 type: group singleFolder: value: assetId: urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 name: My New Folder createdDate: "2024-01-05T14:00:00Z" modifiedDate: "2024-01-10T10:25:30Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /My New Folder ancestors: [] assetType: folder state: active accessErrorFolderCreate: description: | **Folder Create Error** - Access to create a folder is denied value: error_code: access_error message: You do not have permission to create folders. requestId: 123e4567-e89b-12d3-a456-426614174000 singleFile: value: assetType: file assetId: urn:aaid:sc:US:22222222-aaaa-bbbb-cccc-333333333333 name: logo.png createdDate: "2024-02-20T09:10:00Z" modifiedDate: "2024-03-05T11:20:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /Marketing Launch Plan/logo.png ancestors: - urn:aaid:sc:US:11111111-aaaa-bbbb-cccc-222222222222 contentEtag: "1683839000010" mediaType: image/png size: 2418293 state: active ancestorNotFound: description: | **Ancestor Not Found** - The requested ancestor was not found value: error_code: resource_not_found message: The requested ancestor specified by baseAssetId was not found. invalidDestination: description: | **Invalid Destination** - The requested destination (path) is invalid value: error_code: validation_error message: The requested destination (path) is invalid. invalidSize: description: | **Invalid Size** - The requested size is invalid value: error_code: validation_error message: The requested size is invalid. unsupportedMediaType: description: | **Unsupported Media Type** - The requested media type is not supported value: error_code: validation_error message: The requested media type is not supported. responses: paginatedProjectsResponse: description: | **Success** - Paginated response containing an array of project assets with basic information about the project along with paging information. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/paginatedProjects" examples: paginatedProjects: $ref: "#/components/examples/paginatedProjects" unauthorizedResponse: description: | **Unauthorized** - The request requires user authentication headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: unauthorized: $ref: "#/components/examples/unauthorized" rateLimitResponse: description: | **Too Many Requests** - The request was rejected due to rate limiting headers: x-request-id: $ref: "#/components/headers/requestId" retry-after: $ref: "#/components/headers/retryAfter" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: rateLimited: $ref: "#/components/examples/rateLimited" runtimeErrorResponse: description: | **Internal Server Error** - An unexpected error occurred while processing the request headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: runtimeError: $ref: "#/components/examples/runtimeError" accessErrorProjectCreateResponse: description: | **Forbidden** - The user does not have permission to create projects headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: accessProjectCreateError: $ref: "#/components/examples/accessErrorProjectCreate" invalidContentTypeResponse: description: | **Unsupported Media Type** - The server cannot process the request due to an unsupported media type headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidContentType: $ref: "#/components/examples/invalidContentType" matchedEtagResponse: description: | **Success** - The ETag of the asset matches the etag provided in the headers. The client can safely use the cached version of the asset. headers: x-request-id: $ref: "#/components/headers/requestId" etag: $ref: "#/components/headers/etag" accessErrorResponse: description: | **Forbidden** - The user does not have permission to access the resource headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: accessErrorResponse: $ref: "#/components/examples/accessError" resourceNotFoundResponse: description: | **Not Found** - The requested resource was not found headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: resourceNotFound: $ref: "#/components/examples/resourceNotFound" invalidOperationResponse: description: | **Conflict** - The requested operation is invalid based on the current state of the resource headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidOperation: $ref: "#/components/examples/invalidOperation" preconditionFailedResponse: description: | **Precondition Failed** - The request failed due to a precondition headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: etag Mismatch: $ref: "#/components/examples/etagMismatch" paginatedAssetsResponse: description: | **Success** - Paginated response containing an array of object with each element containing basic information about the project, along with paging information. headers: x-request-id: $ref: "#/components/headers/requestId" etag: $ref: "#/components/headers/etag" content: application/json: schema: $ref: "#/components/schemas/paginatedAssets" examples: paginatedAssets: $ref: "#/components/examples/paginatedAssets" assetPermissionResponse: description: | **Success** - Effective permission for the user headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: AssetPermission description: The effective permission for the user properties: role: $ref: "#/components/schemas/roleEnums" examples: assetPermission: value: role: edit 200.getAssetPermissions: description: | **Success** - A list of collaborators and their permissions for the asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/assetPermissionsResponse" examples: All Permissions: $ref: "#/components/examples/200.assetPermissions" 200.patchAssetPermissions: description: | **Success/Partial Success** Patching the permissions was tried and from the response body result of each request can be determined based on the status. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/patchAssetPermissionsResponse" example: direct: additions: - status: failed id: 08D81E3B665BE5640A495C2CA@AdobeOrg type: group error_code: ec message: Failed role: edit - status: successful id: A495C2C08D81E3B665BE5640B@e type: user role: comment - status: failed id: orgEverybody type: predefined error_code: ec message: Failed role: edit updates: - status: failed id: 08D81E3B665BE5640A495C2C@AdobeOrg type: group error_code: ec message: Failed role: edit - status: successful id: orgEverybody type: predefined role: comment deletions: - status: successful id: A495C2C08D81E3B665BE5640@e type: user packageAssetResponse: description: | **Success** - Asynchronous job id along with monitor url headers: x-request-id: $ref: "#/components/headers/requestId" location: $ref: "#/components/headers/location" retry-after: $ref: "#/components/headers/retryAfter" content: application/json: schema: type: object title: packageAssetResponse description: Asynchronous job id along with monitor url properties: jobId: type: string description: The asynchronous job id example: 123e4567-e89b-12d3-a456-426614174000 examples: packageAssetResponse: value: jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9 accessErrorFolderCreateResponse: description: | **Forbidden** - The user does not have permission to create folders headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: accessFolderCreateError: $ref: "#/components/examples/accessErrorFolderCreate" fileDownloadUrlResponse: description: | **Success** - A pre-signed download URL for the asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: FileDownloadUrl description: A pre-signed download URL for the asset properties: url: allOf: - $ref: "#/components/schemas/url" description: The pre-signed URL that supports HTTP range requests for partial downloads urlExpirationDate: allOf: - $ref: "#/components/schemas/date" description: The expiration date of the pre-signed URL size: type: integer description: Size of the file in bytes format: int64 minimum: 0 mediaType: type: string description: The MIME type of the file example: mediaType: application/zip size: 234567890 url: https:///download?signature=abc123 urlExpirationDate: "2025-05-13T10:15:30Z" fileUploadInitResponse: description: | **Success** - Upload Id along with urls for upload headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: FileUploadInitResponse description: Upload Id along with urls for upload properties: uploadId: type: string description: The upload id example: 123e4567-e89b-12d3-a456-426614174000 blockSize: type: integer description: The size of each block in bytes example: 1048576 urlExpirationDate: allOf: - $ref: "#/components/schemas/date" description: The expiration date of the pre-signed URL transferLinks: type: array items: type: object title: TransferLink description: The pre-signed URL pointing to the storage location for the block along with the part number properties: url: allOf: - $ref: "#/components/schemas/url" description: The pre-signed URL pointing to the storage location for the block partNumber: type: integer description: Index of the block (used to identify the order) example: 1 examples: uploadInitResponse: value: blockSize: 10485760 urlExpirationDate: "2025-05-13T09:59:13.267Z" transferLinks: - partNumber: 1 url: https://example.com/temp/block01 - partNumber: 2 url: https://example.com/temp/block02 uploadId: 27ccfae6-72dc-490d-a5c3-0655110cba99 fileUploadFinalizeResponse: description: | **Success** - Asynchronous job id used to call the status endpoint. headers: x-request-id: $ref: "#/components/headers/requestId" retry-after: $ref: "#/components/headers/retryAfter" content: application/json: schema: type: object title: FileUploadFinalizeResponse description: Asynchronous job id used to call the status endpoint. properties: jobId: type: string description: The asynchronous job id example: 123e4567-e89b-12d3-a456-426614174000 examples: uploadFinalizeResponse: value: jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9 requestBodies: projectCreateRequest: required: true content: application/json: schema: type: object title: ProjectCreateRequest description: Represents a request body for creating a project. nullable: false required: - name properties: name: $ref: "#/components/schemas/assetName" patchAssetPermissions: required: true content: application/json: schema: $ref: "#/components/schemas/patchAssetPermissionsRequest" examples: patchPermissions: $ref: "#/components/examples/patchAssetPermissions" folderCreateRequest: required: true content: application/json: schema: type: object title: FolderCreateRequest description: | Represents a request body for creating a folder. --- > NOTE: > The client must supply either > * a `name` (for single folder creation), or > * a `path` (for hierarchy creation) >depending on the type of folder creation requested. --- nullable: false required: - parentId properties: parentId: allOf: - $ref: "#/components/schemas/assetId" description: Asset Id of the parent container (project/folder). name: $ref: "#/components/schemas/assetName" path: $ref: "#/components/schemas/path" examples: Single Folder Create Request: value: name: Marketing parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a Multiple Folders Create Request: value: path: Marketing/2024/CampaignA parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a fileUploadInitRequest: required: true content: application/json: schema: type: object title: FileUploadInitRequest description: | This request body is used to initialize a block based file upload job. properties: size: $ref: "#/components/schemas/fileSize" parentId: type: string description: The assetId of the containing asset name: $ref: "#/components/schemas/assetName" mediaType: type: string description: The MIME type of the file example: image/jpeg blockSize: type: integer description: The size of each block in bytes. The block size returned may differ from the size requested. example: 1048576 required: - size - parentId - name - mediaType fileUploadFinalizeRequest: required: true content: application/json: schema: type: object title: FileUploadFinalizeRequest description: | This request body is used to finalize a block based file upload job. properties: uploadId: type: string description: The upload id example: 123e4567-e89b-12d3-a456-426614174000 usedTransferLinks: type: array description: The transfer links used to upload the file items: type: number description: The part number of the blocks used for uploading the content minItems: 1 required: - uploadId - usedTransferLinks example: uploadId: 123e4567-e89b-12d3-a456-426614174000 usedTransferLinks: - 1 - 3 - 5 x-tagGroups: - name: Asset Operations tags: - Projects - Folders - Files - Jobs