openapi: 3.0.3 info: title: Adobe Cloud Storage and Collaboration version: v1 servers: - url: https://cloudstorage.adobe.io/v1 description: Production Server x-server: prod security: - Authorization: [] tags: - name: 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. - name: Folders description: | A construct that can contain assets and other folders, enabling logical organization of assets. - name: Files description: | Assets typically created through non-Adobe applications. The MIME type indicates the asset type. - name: Brands description: | Brands are collections of reusable assets and guidelines for content reuse across documents. They contain elements such as logos, colors, fonts, and graphics. - name: Jobs description: | Represents long running tasks in the system that are created by invoking specific operations. 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**. > * 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" "401": $ref: "#/components/responses/unauthorizedResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "422": $ref: "#/components/responses/invalidRequestPagedResponse" "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" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: createProject: $ref: "#/components/examples/singleProject" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorProjectCreateResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "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. > * Deleted 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/requestId" responses: "200": description: | **Success** - Retrieved information about the project headers: 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" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" delete: operationId: deleteProject summary: Delete project by ID description: | This endpoint deletes(soft deletion) or permanently deletes(hard deletion) an existing CC Project, identified by its `assetId`, along with all its descendant assets, from the organization’s ESM shared storage. --- > NOTE: > * In order to perform hard deletion, the project must be in DELETED state. > * The requester must have sufficient permission to perform destructive actions on the project. > * If the project is not found or access is denied, appropriate error responses will be returned. --- tags: - Projects parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" - $ref: "#/components/parameters/permanent" responses: "204": description: | **Success** - The project was deleted successfully headers: x-request-id: $ref: "#/components/headers/requestId" "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" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "504": description: | **Operation Timed Out** - The operation took longer than 60 seconds. The operation will continue after the timeout. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: operationTimedOut: $ref: "#/components/examples/operationTimedOut" /projects/{assetId}/rename: post: operationId: renameProject summary: Rename a project. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Projects description: | This endpoint updates the name of an existing Project, identified by its `assetId`, within the organization's ESM shared storage. This operation is only permitted if the requester has appropriate write-level permissions on the project. --- > NOTE: > * Only the name of the project can be modified using this endpoint. > * All other project metadata remains unchanged. > * If the requester lacks the required permissions or the project does not exist, an appropriate error response > will be returned. --- requestBody: $ref: "#/components/requestBodies/projectRenameRequest" responses: "200": description: | **Updated** - The project was renamed successfully. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: renameProject: $ref: "#/components/examples/singleProject" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "412": $ref: "#/components/responses/preconditionFailedResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" "507": $ref: "#/components/responses/storageQuotaExceededResponse" /projects/{assetId}/restore: post: operationId: restoreProject summary: Restore a soft-deleted project. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Projects description: | This endpoint restores an existing project, identified by its `assetId`, within the organization's ESM shared storage to an ACTIVE state. Descendants of the project will have their states recomputed to their previous state. This operation is only permitted if the requester has appropriate write-level permissions on the project. --- > NOTE: > * Projects already in an ACTIVE state will remain ACTIVE and return 200 OK. > * Descendants that were in a DELETED state prior to the deletion of this project will remain DELETED. Their respective descendants will also remain in the DELETED_PARENT or DELETED state as before. > * Hard-deleted projects will return a 404 Not Found error. > * If the requester lacks the required permissions or the project does not exist, an appropriate error response > will be returned. --- responses: "200": description: | **Success** - Retrieved information about the project headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectAsset" examples: restoreProject: $ref: "#/components/examples/singleProject" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/children: get: operationId: getProjectChildren summary: Get Paginated List of Children of 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" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "422": $ref: "#/components/responses/invalidRequestPagedResponse" "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 `orgEverybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/projectPermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{assetId}/roles: get: operationId: getProjectRoles summary: Get Roles for a Project tags: - Projects description: | The endpoint retrieves the **explicit roles** 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 roles 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 role 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/getAssetRolesResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" patch: operationId: patchProjectRoles summary: Patch Roles for a Project tags: - Projects description: | This endpoint is used to manage the direct roles of a specific project, identified by its `assetId`. It allows clients to perform multiple types of role 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. > * Role 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/patchAssetRoles" responses: "200": $ref: "#/components/responses/patchAssetRolesResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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/{projectId}/references: post: operationId: addProjectReference summary: Add a brand reference to a project tags: - Projects description: | Adds a reference (link) to a brand within a project. References allow projects to include content from brands. A project can have a maximum of 200 references. parameters: - name: projectId in: path required: true description: The unique identifier (URN) of the project to add the reference to. schema: type: string - $ref: "#/components/parameters/requestId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/addProjectReferenceRequest" responses: "201": description: "**Created** - The reference was successfully added to the project." headers: x-request-id: $ref: "#/components/headers/requestId" Location: description: URL of the newly created reference. schema: type: string content: application/json: schema: $ref: "#/components/schemas/projectReferenceResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" get: operationId: listProjectReferences summary: List brand references for a project tags: - Projects description: | Returns a list of brand references associated with the specified project. parameters: - name: projectId in: path required: true description: The unique identifier (URN) of the project to list the references from. schema: type: string - $ref: "#/components/parameters/requestId" responses: "200": description: "**Success** - List of brand references for the project." headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/projectReferencesListResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /projects/{projectId}/references/{referenceId}: delete: operationId: removeProjectReference summary: Remove a brand reference from a project tags: - Projects description: | Removes a brand reference from a project identified by its referenceId. parameters: - name: projectId in: path required: true description: The unique identifier (URN) of the project to remove the reference from. schema: type: string - name: referenceId in: path required: true description: The unique identifier (URN) of the referenced brand to remove. schema: type: string - $ref: "#/components/parameters/requestId" responses: "204": description: "**No Content** - The reference was successfully removed." headers: x-request-id: $ref: "#/components/headers/requestId" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "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" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/folderAsset" examples: createFolder: $ref: "#/components/examples/singleFolder" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorFolderCreateResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "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/requestId" responses: "200": description: | **Success** - Retrieved information about the folder headers: 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" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" delete: operationId: deleteFolder summary: Delete folder by ID description: | This endpoint deletes(soft deletion) or permanently deletes(hard deletion) an existing folder, identified by its `assetId`, along with all its descendant assets, from the organization’s ESM shared storage. --- > NOTE: > * In order to perform hard deletion, the folder must be in DELETED state. > * The requester must have sufficient permission to perform destructive actions on the folder. > * If the folder is not found or access is denied, appropriate error responses will be returned. --- tags: - Folders parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" - $ref: "#/components/parameters/permanent" responses: "204": description: | **Success** - The folder was deleted successfully headers: x-request-id: $ref: "#/components/headers/requestId" "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" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "504": description: | **Operation Timed Out** - The operation took longer than 60 seconds. The operation will continue after the timeout. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: operationTimedOut: $ref: "#/components/examples/operationTimedOut" /folders/{assetId}/rename: post: operationId: renameFolder summary: Rename a folder. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Folders description: | This endpoint updates the name of an existing Folder, identified by its `assetId`. This operation is only permitted if the requester has appropriate write-level permissions on the folder. --- > NOTE: > * Only the name of the folder can be modified using this endpoint. > * All other folder metadata remains unchanged. > * If the requester lacks the required permissions or the folder does not exist, an appropriate error response > will be returned. --- requestBody: $ref: "#/components/requestBodies/folderRenameRequest" responses: "200": description: | **Updated** - The folder was renamed successfully. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/folderAsset" examples: renameFolder: $ref: "#/components/examples/singleFolder" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" "507": $ref: "#/components/responses/storageQuotaExceededResponse" /folders/{assetId}/restore: post: operationId: restoreFolder summary: Restore a soft-deleted folder. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Folders description: | This endpoint restores an existing folder, identified by its `assetId`, within the organization's ESM shared storage to an ACTIVE state. Descendants of the folder will have their states recomputed to their previous state. This operation is only permitted if the requester has appropriate write-level permissions on the folder. --- > NOTE: > * Folders already in an ACTIVE state will remain ACTIVE and return 200 OK. > * Restore operations can only be invoked on roots of DELETED trees. Restore calls made on assets in a DELETED_PARENT state will return a 409 Conflict error. > * Descendants of this folder that were in a DELETED state prior its deletion will remain DELETED. Their respective descendants will also remain in a DELETED_PARENT or DELETED state as before. > * Hard-deleted folders will return a 404 Not Found error. > * If an asset with the same path already exists, the restored folder will be renamed automatically. > * If the requester lacks the required permissions or the folder does not exist, an appropriate error response > will be returned. --- responses: "200": description: | **Success** - Retrieved information about the folder headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/folderAsset" examples: restoreFolder: $ref: "#/components/examples/singleFolder" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /folders/{assetId}/children: get: operationId: getFolderChildren summary: Get Paginated List of Children of 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" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "422": $ref: "#/components/responses/invalidRequestPagedResponse" "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 `orgEverybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/folderPermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "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/requestId" responses: "200": description: | **Success** - Retrieved information about the file headers: 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" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" delete: operationId: deleteFile summary: Delete file by ID description: | This endpoint deletes(soft deletion) or permanently deletes(hard deletion) an existing file, identified by its `assetId`, from the organization’s ESM shared storage. --- > NOTE: > * In order to perform hard delete, the file must be in DELETED state. > * The requester must have sufficient permissions to perform destructive actions on the file. > * If the file is not found or access is denied, appropriate error responses will be returned. --- tags: - Files parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" - $ref: "#/components/parameters/permanent" responses: "204": description: | **Success** - The file was deleted successfully headers: x-request-id: $ref: "#/components/headers/requestId" "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" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" /files/{assetId}/rename: post: operationId: renameFile summary: Rename a file. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Files description: | This endpoint updates the name of an existing File, identified by its `assetId`. This operation is only permitted if the requester has appropriate write-level permissions on the file. --- > NOTE: > * Only the name of the file can be modified using this endpoint. > * All other file metadata remains unchanged. > * If the requester lacks the required permissions or the file does not exist, an appropriate error response > will be returned. --- requestBody: $ref: "#/components/requestBodies/fileRenameRequest" responses: "200": description: | **Updated** - The file was renamed successfully. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/fileAsset" examples: renameFile: $ref: "#/components/examples/singleFile" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" "507": $ref: "#/components/responses/storageQuotaExceededResponse" /files/{assetId}/restore: post: operationId: restoreFile summary: Restore a soft-deleted file. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Files description: | This endpoint restores an existing file, identified by its `assetId`, within the organization's ESM shared storage to an ACTIVE state. This operation is only permitted if the requester has appropriate write-level permissions on the file. --- > NOTE: > * Files already in an ACTIVE state will remain ACTIVE and return 200 OK. > * Restore calls made on assets in a DELETED_PARENT state will return a 409 Conflict error. > * Hard-deleted files will return a 404 Not Found error. > * If an asset with the same path already exists, the restored file will be renamed automatically. > * If the requester lacks the required permissions or the file does not exist, an appropriate error response > will be returned. --- responses: "200": description: | **Success** - Retrieved information about the file headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/fileAsset" examples: restoreFile: $ref: "#/components/examples/singleFile" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "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 `orgEverybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/filePermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/roles: get: operationId: getFileRoles summary: Get Roles for a File tags: - Files description: | The endpoint retrieves the **explicit roles** assigned to all users and groups for a specific file, identified by its `assetId`. This includes only the **direct access control entries** defined on the file itself and does not include any roles that are inherited from parent folders or the containing project. --- > NOTE: > * The response lists all users and groups that have direct access to the file, along with their respective > roles (e.g., comment, edit). > * This data is useful for auditing and role management but does not represent the full effective access > unless inheritance is also considered. > * 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. --- parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/getAssetRolesResponse" "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: patchFileRoles summary: Patch Roles for a File tags: - Files description: | This endpoint is used to manage the direct roles of a specific file, identified by its `assetId`. It allows clients to perform multiple types of role 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. > * Role changes apply directly to the file. > ## 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/patchAssetRoles" responses: "200": $ref: "#/components/responses/patchAssetRolesResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" /files/{assetId}/copy: post: operationId: copyFile summary: Copies a file to a new location. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Files description: | This endpoint performs an asynchronous copy of an existing file asset, identified by its `assetId`, into another folder or project. The operation requires the requester to have, at minimum, the following roles: | Location | Role(s) | | -------- | ------- | | Source | comment | | Target | edit | --- > NOTE: > * If the requester lacks the required roles or the file does not exist, an appropriate error response will be > returned. --- requestBody: $ref: "#/components/requestBodies/fileCopyRequest" responses: "202": $ref: "#/components/responses/fileCopyAcceptedResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" "507": $ref: "#/components/responses/storageQuotaExceededResponse" /files/{assetId}/move: post: operationId: moveFile summary: Move a file to a new location. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" tags: - Files description: | This endpoint performs an asynchronous move of an existing file asset, identified by its `assetId`, into another folder or project. The operation requires the requester to have, at minimum, the following roles: | Location | Role(s) | | ----------------- | ------- | | Source | comment | | Source's parent | edit | | Target | edit | --- > NOTE: > * If the requester lacks the required roles or the file does not exist, an appropriate error response will be > returned. --- requestBody: $ref: "#/components/requestBodies/fileMoveRequest" responses: "202": $ref: "#/components/responses/fileMoveAcceptedResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" "507": $ref: "#/components/responses/storageQuotaExceededResponse" /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/fileDownloadOKResponse" "202": $ref: "#/components/responses/fileDownloadAcceptedResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "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/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" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "412": $ref: "#/components/responses/preconditionFailedResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/upload/init: x-filetype-restriction: true 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. --- > NOTE: > For files 10 MB or larger, direct upload is not supported. Clients must use this block-based upload workflow. > block-based transfer is allowed for any size --- ## 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": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" invalidNameType: $ref: "#/components/examples/invalidNameType" invalidNameValue: $ref: "#/components/examples/invalidNameValue" 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 success, 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": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" invalidFieldType: $ref: "#/components/examples/invalidUploadIdType" invalidFieldValue: $ref: "#/components/examples/invalidUsedTransferLinksValue" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/upload/init: post: operationId: initBlockBasedFileReplacement summary: Initialize a block based file replacement job description: | Initializes a block based replacement job for an existing file. The init response provides a set of pre-signed URLs for uploading individual blocks, transferred over separate requests. Once the replacement file content is uploaded, the finalize endpoint is called to finalize the replacement. The file's `assetId`, permissions, and metadata are preserved while the content is replaced. --- > NOTE: > For files 10 MB or larger, direct replacement is not supported. Clients must use this block-based replacement workflow. > block-based transfer is allowed for any size --- ## Replacement Flow Overview ### 1. Initiate Replacement: Client sends a POST request to initiate the block replacement 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 Replacement: After all blocks are uploaded, the client calls the [Block Finalize URL](#/Files/finalizeBlockBasedFileReplacement) to trigger the replacement. ### 4. Monitor: Finalize operation's response includes a Monitor URL to check the final status. # Initialize the Block-Based Replacement This endpoint allows clients to initiate the replacement of an existing file's content using block-based transfer. --- > NOTE: > * The expiration duration of transfer URLs is explicitly provided to the client in the response > * The Content-Type must match the existing file's media type. Attempting to change the content type will result in a **415 Unsupported Media Type** error. --- tags: - Files parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/fileReplaceInitRequest" responses: "200": $ref: "#/components/responses/fileUploadInitResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/contentTypeChangeNotAllowedResponse" "422": description: | **Unprocessable Request** - 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" invalidSize: $ref: "#/components/examples/invalidSize" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /files/{assetId}/upload/finalize: post: operationId: finalizeBlockBasedFileReplacement summary: Finalize a block based file replacement job description: | This endpoint finalizes the block replacement process by initiating an asynchronous job that will merge all uploaded blocks and replace the existing file's content. The file's `assetId`, permissions, and metadata are preserved. --- > NOTE: > ### Validation and Behavior for Finalize (Block-Based Replacement) > The following rules govern how the server interprets the finalization request for a block-based replacement: > > #### 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/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/fileUploadFinalizeRequest" responses: "202": $ref: "#/components/responses/fileUploadFinalizeResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": 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: expiredUpload: $ref: "#/components/examples/expiredOrAlreadyUsed" alreadyFinalized: $ref: "#/components/examples/expiredOrAlreadyUsed" invalidOperation: $ref: "#/components/examples/invalidOperation" "415": $ref: "#/components/responses/contentTypeChangeNotAllowedResponse" "422": description: | **Unprocessable Request** - 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" invalidFieldType: $ref: "#/components/examples/invalidUploadIdType" invalidFieldValue: $ref: "#/components/examples/invalidUsedTransferLinksValue" "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" "406": $ref: "#/components/responses/notAcceptableResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands: post: operationId: createBrand summary: Create a new Brand parameters: - $ref: "#/components/parameters/requestId" tags: - Brands description: | This endpoint creates an empty Brand that can be populated later with elements such as logos, colors, fonts, and graphics. The brand is created within a specified project, provided the user has the necessary permissions. requestBody: $ref: "#/components/requestBodies/brandCreateRequest" responses: "201": description: | **Created** - The brand was created successfully. headers: location: $ref: "#/components/headers/location" x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandAsset" examples: createBrand: $ref: "#/components/examples/singleBrand" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}: get: operationId: getBrand summary: Get a brand by ID description: | This endpoint retrieves full metadata for a specific Brand identified by its assetId. tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved information about the brand headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandAsset" examples: singleBrand: $ref: "#/components/examples/singleBrand" "400": description: | **Bad Request** - The request is invalid. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" "401": description: | **Unauthorized** - The authorization token is not accepted. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: unauthorized: $ref: "#/components/examples/unauthorized" "403": description: | **Forbidden** - Client ID is not authorized, or access is denied. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: accessErrorResponse: $ref: "#/components/examples/accessError" "404": description: | **Not Found** - The specified resource could not be found. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: resourceNotFound: $ref: "#/components/examples/resourceNotFound" "406": $ref: "#/components/responses/notAcceptableResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors (invalid assetId, invalid assetType). headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidAssetIdValue: $ref: "#/components/examples/invalidAssetIdValue" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" delete: operationId: deleteBrand summary: Delete brand by ID description: | This endpoint deletes(soft deletion) or permanently deletes(hard deletion) an existing Brand, identified by its `assetId`. tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" - $ref: "#/components/parameters/permanent" responses: "204": description: | **Success** - The brand was deleted successfully headers: x-request-id: $ref: "#/components/headers/requestId" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" /brands/{assetId}/rename: post: operationId: renameBrand summary: Rename a brand. parameters: - name: assetId in: path required: true description: | The unique identifier (URN) of the brand to be renamed. schema: $ref: "#/components/schemas/assetId" - $ref: "#/components/parameters/requestId" tags: - Brands description: | This endpoint updates the name of an existing Brand, identified by its `assetId`. --- > NOTE: > * Only the name of the brand can be modified using this endpoint. > * All other brand metadata remains unchanged. > * If the requester lacks the required permissions or the brand does not exist, an appropriate error response > will be returned. --- requestBody: $ref: "#/components/requestBodies/brandRenameRequest" responses: "200": description: | **Updated** - The brand was renamed successfully. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandAsset" examples: renameBrand: $ref: "#/components/examples/renameBrand" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements: get: operationId: listBrandElements summary: List elements inside a brand tags: - Brands description: | Returns a paginated list of elements inside the specified brand. Use the `cursor` parameter to fetch subsequent pages. parameters: - $ref: "#/components/parameters/assetId" - name: limit in: query required: false description: Maximum number of items per page. schema: type: integer format: int32 - name: start in: query required: false description: Zero-based start offset. Required when limit is specified and cursor is absent. schema: type: integer format: int32 - name: sortBy in: query required: false description: "Sort order. Fields: name, created, modified. Prefix - for descending, + (optional) for ascending." schema: type: string default: +name - name: mediaType in: query required: false description: "Filter elements by media type. Example: application/vnd.adobe.element.image+dcx" schema: type: string - name: cursor in: query required: false description: Cursor used for fetching the next set of results. schema: type: string - $ref: "#/components/parameters/requestId" responses: "200": description: "**Success** - Paginated list of brand elements." headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandElementsListResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements/init: post: operationId: initBrandElementUpload summary: Initialize a brand element binary upload description: | This endpoint initializes a block-based upload session for a new binary element within a Brand identified by its `assetId`. It validates the element metadata, reserves upload capacity, and returns pre-signed transfer URLs along with an `uploadId` to be used in the finalize call. --- > NOTE: > This flow is intended for binary brand elements such as images, videos, and other files. > > After receiving `transferLinks`, clients upload raw binary blocks directly to the provided URLs: > **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`), the operation may fail. --- tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/brandElementUploadInitRequest" responses: "200": $ref: "#/components/responses/fileUploadInitResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" invalidNameType: $ref: "#/components/examples/invalidNameType" invalidNameValue: $ref: "#/components/examples/invalidNameValue" invalidAssetIdValue: $ref: "#/components/examples/invalidAssetIdValue" invalidSize: $ref: "#/components/examples/invalidSize" unsupportedMediaType: $ref: "#/components/examples/unsupportedMediaType" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements/finalize: post: operationId: finalizeBrandElementUpload summary: Finalize a brand element binary upload description: | This endpoint finalizes a block-based binary upload for a brand element, waits for the repository upload to complete, creates the brand element, and returns the created element. --- > NOTE: > * Clients must provide the `uploadId` received from the init response. > * `usedTransferLinks` must list the uploaded part numbers in the order they should be stitched together. > * Upload sessions may expire before finalization if the transfer URLs are no longer valid. --- tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/brandElementUploadFinalizeRequest" responses: "202": description: | **Accepted** - The brand element upload finalize has been accepted and is being processed asynchronously. Use the returned `jobId` to poll for the result via the status endpoint. headers: Retry-After: schema: type: integer description: Suggested number of seconds to wait before polling the status endpoint. x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandElementFinalizeAcceptedResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "409": $ref: "#/components/responses/invalidOperationResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors (invalid assetId, invalid assetType). headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: invalidAssetIdValue: $ref: "#/components/examples/invalidAssetIdValue" invalidFieldType: $ref: "#/components/examples/invalidUploadIdType" invalidFieldValue: $ref: "#/components/examples/invalidUsedTransferLinksValue" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements/content: post: operationId: createJsonBrandElement summary: Create a JSON brand element description: | Creates a new JSON-based element (such as a font definition or color theme) within a Brand identified by its `assetId`. Unlike binary element upload, this endpoint accepts the element content directly as the `data` part of a multipart request and returns the created element synchronously. The `Content-Type` of the `data` part determines the element's media type and must be a supported JSON element media type (e.g. `application/vnd.adobe.element.font+json` or `application/vnd.adobe.element.colortheme+json`). tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" requestBody: $ref: "#/components/requestBodies/brandElementContentRequest" responses: "201": description: | **Created** - The brand element was successfully created. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandElement" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" invalidNameType: $ref: "#/components/examples/invalidNameType" invalidNameValue: $ref: "#/components/examples/invalidNameValue" invalidAssetIdValue: $ref: "#/components/examples/invalidAssetIdValue" unsupportedMediaType: $ref: "#/components/examples/unsupportedMediaType" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements/{elementId}: delete: operationId: deleteBrandElement summary: Delete a brand element description: | Deletes an element from the specified brand. tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - name: elementId in: path required: true description: The unique identifier of the element inside the brand. schema: type: string minLength: 1 - $ref: "#/components/parameters/requestId" responses: "204": description: "**No Content** - The element was deleted successfully." headers: x-request-id: $ref: "#/components/headers/requestId" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" get: operationId: getBrandElement summary: Get a brand element by ID description: | Returns detailed information about a single element inside a Brand identified by its `assetId`. tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - name: elementId in: path required: true description: The unique identifier of the element inside the brand. schema: type: string minLength: 1 - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved information about the brand element. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/brandElement" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/elements/{elementId}/content: get: operationId: getBrandElementContent summary: Get the content of a JSON brand element description: | Returns the representations (inline JSON content) of a brand element identified by its `elementId`. This endpoint is intended for JSON-based elements such as fonts and color themes. tags: - Brands parameters: - $ref: "#/components/parameters/assetId" - name: elementId in: path required: true description: The unique identifier of the element inside the brand. schema: type: string minLength: 1 - $ref: "#/components/parameters/requestId" responses: "200": description: | **Success** - Retrieved the content of the brand element. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: array items: type: object examples: font: summary: Font element data value: - name: Abolition Soft Oblique postScriptName: Abolition-SoftOblique fontId: TkD-25250-2aaf0176c5aafdb3cd9a0b0cd799fc0e45ad190e family: Abolition style: Soft Oblique premium: true isUserAdded: false colorTheme: summary: Color theme element data value: - mood: calm swatches: - mode: RGB value: - 0 - 114 - 239 type: process "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "422": $ref: "#/components/responses/unprocessableEntityResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" /brands/{assetId}/roles: get: operationId: getBrandRoles summary: Get All roles for a Brand tags: - Brands description: | The endpoint retrieves the **explicit roles** assigned to all users and groups for a specific brand, identified by its `brandId`. This includes only the **direct access control entries** defined on the brand itself. --- > NOTE: > * The response lists all users and groups that have direct access to the brand, along with their respective > roles (e.g., comment, edit). > * This data is useful for auditing and role management but does not represent the full effective access > unless inheritance is also considered. > * The brand must exist and the requester must have at least read-level access. If the brand 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/getAssetRolesResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "422": description: | **Unprocessable Entity** - The request cannot be processed due to semantic errors (invalid brandId, invalid assetType). headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" "429": $ref: "#/components/responses/rateLimitResponse" "500": $ref: "#/components/responses/runtimeErrorResponse" patch: operationId: patchBrandRoles summary: Patch Roles for a Brand tags: - Brands description: | This endpoint is used to manage the direct roles of a specific brand, identified by its `brandId`. It allows clients to perform multiple types of role 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. > * Role changes apply directly to the brand. > ## 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/patchAssetRoles" responses: "200": $ref: "#/components/responses/patchAssetRolesResponse" "400": $ref: "#/components/responses/invalidRequestResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "415": $ref: "#/components/responses/invalidContentTypeResponse" "422": description: | **Unprocessable Request** - 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" /brands/{assetId}/effective-permission: get: operationId: getBrandEffectivePermission summary: Get User's Effective Permissions for a Brand tags: - Brands description: | The endpoint retrieves the **effective permission (role)** assigned to the user for a specific brand, identified by its `assetId`. It evaluates the user's access based on: * **Direct permissions** assigned to the brand. * **Predefined principals**, such as `orgEverybody` or group-based access rules. parameters: - $ref: "#/components/parameters/assetId" - $ref: "#/components/parameters/requestId" responses: "200": $ref: "#/components/responses/brandEffectivePermissionResponse" "401": $ref: "#/components/responses/unauthorizedResponse" "403": $ref: "#/components/responses/accessErrorResponse" "404": $ref: "#/components/responses/resourceNotFoundResponse" "406": $ref: "#/components/responses/notAcceptableResponse" "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. --- > NOTE: > This list is not exhaustive and will be updated as new error codes are added. Clients should expect new error codes to be added in the future. --- enum: - bad_request - unauthorized - access_error - resource_not_found - not_acceptable - invalid_operation - conflict - cursor_expired - precondition_failed - etag_mismatch - payload_too_large - invalid_content_type - validation_error - resource_too_large - rate_limited - runtime_error - not_implemented - operation_timeout - storage_quota_exceeded assetTypeEnums: type: string title: AssetType description: | Describes the type of asset. --- > NOTE: > This list is not exhaustive and will be updated as new asset types are added. Clients should expect new asset types to be added in the future. --- enum: - folder - file - project - library - cloudDoc - brand jobTypeEnums: type: string title: JobTypeEnums description: | It describes the type of asynchronous job, depends on the original API invocation that created the job. --- > NOTE: > This list is not exhaustive and will be updated as new job types are added. Clients should expect new job types to be added in the future. --- enum: - file_upload - file_download - file_copy - file_move - folder_copy - folder_move - project_package - brand_element_finalize jobStatusEnums: type: string title: JobStatusEnums description: | It describes the status of an asynchronous job. --- > NOTE: > This list is not exhaustive and will be updated as new job types are added. Clients should expect new job types to be added in the future. --- enum: - running - succeeded - failed - partially_succeeded requestId: type: string title: RequestId description: An identifier provided by the client to identify the request. example: "1234567890" minLength: 1 maxLength: 128 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 minLength: 1 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 - deleted - deleted_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 additionalProperties: true assetName: type: string description: | The name of the asset (including the extension, in case of a file) The name must not be a * reserved Windows name - `CON` - `PRN` - `AUX` - `NUL` - `COM1` through `COM9` - `LPT1` through `LPT9` * contain any of the following characters: - `\` - `/` - `:` - `*` - `?` - `"` - `|` - `>` - `<` maxLength: 255 nullable: false pattern: ^(?!^([Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])$)[^\\\/:*?"|><]+$ autorename: type: boolean title: Autorename description: | Controls whether to automatically rename assets when name conflicts occur during create, rename, copy, move, or restore operations. - **false**: Operation fails with 409 Conflict if a name collision occurs (default) - **true**: System automatically renames the asset by appending a uniqueness token consisting of a non-breaking space(\u00A0) followed by a counter in round parentheses, e.g. "\u00A0(1)" default: false example: true operationOptions: type: object title: OperationOptions description: | Optional configuration for operation behavior. This object allow clients to customize how operations are executed. properties: autorename: $ref: "#/components/schemas/autorename" 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 required: - assetType - mediaType - size 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 brandAsset: type: object title: BrandAsset description: Represents a brand in the system. A brand is a collection of reusable assets, containing elements such as logos, colors, fonts, and graphics. allOf: - $ref: "#/components/schemas/fileAsset" - type: object properties: assetType: type: string default: brand elementsCount: type: integer description: The number of elements inside the brand example: 0 required: - assetType asset: description: | Represents a generic asset in the system. required: - assetType oneOf: - $ref: "#/components/schemas/fileAsset" - $ref: "#/components/schemas/folderAsset" - $ref: "#/components/schemas/projectAsset" - $ref: "#/components/schemas/brandAsset" discriminator: propertyName: assetType mapping: file: "#/components/schemas/fileAsset" folder: "#/components/schemas/folderAsset" project: "#/components/schemas/projectAsset" brand: "#/components/schemas/brandAsset" 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. - `undefined` - In some cases, a permission that cannot be expressed by `edit` or `comment` is returned as `undefined`. The user has some underlying permission to the asset, but the access is not specific enough to be classified as `edit` or `comment`. User operations may be limited. --- > NOTE: > This list is not exhaustive and will be updated as roles are added. Clients should expect new roles to be added in the future. --- enum: - edit - comment - undefined example: edit commonPermissions: type: object title: CommonPermissions description: Common Permissions for the user on any kind of asset properties: can_share: type: boolean description: Whether the user can share the asset with other users default: false can_comment: type: boolean description: Whether the user can comment on the asset default: false can_download_assets: type: boolean description: Whether the user can download the asset default: false required: - can_share - can_comment - can_download_assets containerOnlyPermissions: type: object title: ContainerOnlyPermissions description: The permissions for the user applicable to container type of asset properties: can_move_assets_inside: type: boolean description: Whether the user can move assets inside the container default: false can_move_assets_outside: type: boolean description: Whether the user can move assets outside the container default: false required: - can_move_assets_inside - can_move_assets_outside projectPermissions: type: object title: ProjectPermissions description: The permissions for the user on a project allOf: - $ref: "#/components/schemas/commonPermissions" - $ref: "#/components/schemas/containerOnlyPermissions" - type: object properties: can_edit_project: type: boolean description: Whether the user can edit the project default: false can_view_project: type: boolean description: Whether the user can view the project default: false can_restore: type: boolean description: Whether the user can restore the project default: false can_delete: type: boolean description: Whether the user can soft delete the project default: false can_permanent_delete: type: boolean description: Whether the user can permanently delete the project default: false required: - can_edit_project - can_view_project - can_restore - can_delete - can_permanent_delete baseDirectRoleEntry: type: object title: BaseDirectRoleEntry 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 userDirectRoleEntry: type: object title: UserDirectRoleEntry allOf: - $ref: "#/components/schemas/baseDirectRoleEntry" - type: object properties: type: type: string default: user email: type: string format: email description: Email of the user. required: - type - email groupDirectRoleEntry: type: object title: GroupDirectRoleEntry allOf: - $ref: "#/components/schemas/baseDirectRoleEntry" - type: object properties: type: type: string default: group organizationName: type: string description: Name of the organization. required: - type - organizationName predefinedGroupsDirectRoleEntry: type: object title: PredefinedGroupsDirectRoleEntry allOf: - $ref: "#/components/schemas/baseDirectRoleEntry" - type: object properties: type: type: string default: predefined organizationName: type: string description: Name of the organization. required: - type - organizationName directRoleEntry: type: object title: DirectRoleEntry description: Represents a principal (user, group, or predefined groups) with associated role. oneOf: - $ref: "#/components/schemas/userDirectRoleEntry" - $ref: "#/components/schemas/groupDirectRoleEntry" - $ref: "#/components/schemas/predefinedGroupsDirectRoleEntry" discriminator: propertyName: type mapping: user: "#/components/schemas/userDirectRoleEntry" group: "#/components/schemas/groupDirectRoleEntry" predefined: "#/components/schemas/predefinedGroupsDirectRoleEntry" pendingRoleEntry: type: object title: PendingRoleEntry description: Represents a pending role 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 assetRolesResponse: type: object title: AssetRolesResponse properties: direct: type: array title: Direct Roles items: $ref: "#/components/schemas/directRoleEntry" default: [] pending: type: array title: Pending Invitations items: $ref: "#/components/schemas/pendingRoleEntry" default: [] principalTypeEnums: description: | Represents all the types of principals --- > Note: The list is not exhaustive and will be updated as new types of principals are added. --- type: string enum: - user - group - predefined patchAssetRolesRequest: type: object title: PatchAssetRolesRequest description: Represents the request body for a patch operation on roles for an asset properties: direct: type: object title: DirectRolesModification properties: additions: type: array title: AdditionsList description: Represents a list of users or groups that are being granted role for an asset items: description: Represents a user or group that is being granted role for an asset type: object title: NewRoleEntry 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 | **Note for Predefined Principals:** - `_everybody`: Limited to `comment` (grants access to all org users) - `authenticated`: Can have `comment` or `edit` roles (requires authentication) - `all`: Read-only principal, cannot be added to new permissions 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: UpdatedRoleEntry 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: DeletionRoleEntry properties: id: $ref: "#/components/schemas/principalId" type: $ref: "#/components/schemas/principalTypeEnums" maxItems: 10 default: [] required: - direct basePatchRoleEntry: type: object title: BasePatchRoleEntry description: Represents a base role entry properties: id: $ref: "#/components/schemas/principalId" type: $ref: "#/components/schemas/principalTypeEnums" required: - id - type successfulPatchRoleEntry: description: Represents a successful role entry title: SuccessfulPatchRoleEntry type: object allOf: - $ref: "#/components/schemas/basePatchRoleEntry" - type: object properties: status: type: string default: successful role: $ref: "#/components/schemas/roleEnums" required: - status failedPatchRoleEntry: description: Represents a failed role entry title: FailedPatchRoleEntry type: object allOf: - $ref: "#/components/schemas/basePatchRoleEntry" - 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 pendingPatchRoleEntry: description: Represents a pending role entry title: PendingPatchRoleEntry type: object allOf: - $ref: "#/components/schemas/basePatchRoleEntry" - 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 patchRoleResultEntry: description: | Represents a role patch result entry. title: PatchRoleResultEntry required: - status oneOf: - $ref: "#/components/schemas/successfulPatchRoleEntry" - $ref: "#/components/schemas/failedPatchRoleEntry" - $ref: "#/components/schemas/pendingPatchRoleEntry" discriminator: propertyName: status mapping: successful: "#/components/schemas/successfulPatchRoleEntry" failed: "#/components/schemas/failedPatchRoleEntry" pending: "#/components/schemas/pendingPatchRoleEntry" patchAssetRolesResponse: type: object title: PatchAssetRolesResponse properties: direct: title: PatchAssetDirectRolesResult type: object properties: additions: type: array title: AdditionsList description: Status of each role addition. items: $ref: "#/components/schemas/patchRoleResultEntry" default: [] updates: type: array title: UpdatesList description: Status of each role update. items: $ref: "#/components/schemas/patchRoleResultEntry" default: [] deletions: type: array title: DeletionsList description: Status of each role deletion. items: $ref: "#/components/schemas/patchRoleResultEntry" default: [] required: - direct projectReferenceResponse: type: object title: ProjectReferenceResponse description: Represents a brand reference associated with a project. properties: referenceId: type: string description: The asset ID (URN) of the referenced brand. example: urn:aaid:sc:US:a0620477-6ba4-3c41-9a4c-ffd7a4a60291 referenceType: type: string description: The type of the reference. example: brand asset: $ref: "#/components/schemas/brandAsset" projectReferencesListResponse: type: object title: ProjectReferencesListResponse description: A list of brand references associated with a project. properties: items: type: array description: The list of brand references. items: $ref: "#/components/schemas/projectReferenceResponse" addProjectReferenceRequest: type: object title: AddProjectReferenceRequest description: Request body for adding a brand reference to a project. properties: assetId: type: string description: The asset ID (URN) of the brand to reference. example: urn:aaid:sc:US:a0620477-6ba4-3c41-9a4c-ffd7a4a60291 referenceType: type: string description: The type of the reference. example: brand required: - assetId - referenceType copyOperationOptions: type: object title: CopyOperationOptions description: | Optional configuration for controlling common aspects of copy operation. This object allows clients to customize how copy operations are executed. allOf: - $ref: "#/components/schemas/operationOptions" - type: object copyRequest: type: object title: CopyRequest description: | Represents the request body for a copy operation on an asset. nullable: false required: - parentId properties: parentId: allOf: - $ref: "#/components/schemas/assetId" description: Asset Id of the target parent container (project/folder). name: $ref: "#/components/schemas/assetName" options: $ref: "#/components/schemas/copyOperationOptions" jobId: type: string title: JobId description: A globally unique identifier for the asynchronous job moveOperationOptions: type: object title: MoveOperationOptions description: | Optional configuration for controlling common aspects of move operation. This object allows clients to customize how move operations are executed. allOf: - $ref: "#/components/schemas/operationOptions" - type: object moveRequest: type: object title: MoveRequest description: | Represents the request body for a move operation on an asset. nullable: false required: - parentId properties: parentId: allOf: - $ref: "#/components/schemas/assetId" description: Asset Id of the target parent container (project/folder). name: $ref: "#/components/schemas/assetName" options: $ref: "#/components/schemas/moveOperationOptions" commonNonProjectPermissions: type: object title: NonProjectPermissions description: The permissions for the user applicable to non-project type of asset properties: can_edit_assets: type: boolean description: Whether the user can edit the asset default: false can_view_assets: type: boolean description: Whether the user can view the asset default: false can_restore_assets: type: boolean description: Whether the user can restore the asset default: false can_delete_assets: type: boolean description: Whether the user can soft delete the asset default: false can_permanent_delete_assets: type: boolean description: Whether the user can permanently delete the asset default: false required: - can_edit_assets - can_view_assets - can_restore_assets - can_delete_assets - can_permanent_delete_assets folderPermissions: type: object title: FolderPermissions description: The permissions for the user on a folder allOf: - $ref: "#/components/schemas/commonPermissions" - $ref: "#/components/schemas/containerOnlyPermissions" - $ref: "#/components/schemas/commonNonProjectPermissions" filePermissions: type: object title: FilePermissions description: The permissions for the user on a file allOf: - $ref: "#/components/schemas/commonPermissions" - $ref: "#/components/schemas/commonNonProjectPermissions" url: type: string title: URL description: A URL for the asset format: uri fileDownloadOKResponse: title: FileDownloadOKResponse 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://cloud-storage.adobe.io/download?signature=abc123 urlExpirationDate: "2025-05-13T10:15:30Z" fileSize: type: integer title: FileSize description: The size of the file in bytes. minimum: 1 format: int64 example: 1048576 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 - file_download - file_copy - file_move - folder_copy - folder_move - project_package --- > NOTE: > This list is not exhaustive and will be updated as new job types are added. Clients should expect new job types to be added in the future. --- 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 projectPackageSucceededJobStatus: type: object title: ProjectPackageSucceededJobStatus description: Represents the status of a project package 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 fileDownloadSucceededJobStatus: type: object title: FileDownloadSucceededJobStatus description: Represents the status of a file download succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded downloadResponse: $ref: "#/components/schemas/fileDownloadOKResponse" required: - downloadResponse - status fileCopySucceededJobStatus: type: object title: FileCopySucceededJobStatus description: Represents the status of a file copy succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded asset: $ref: "#/components/schemas/fileAsset" required: - asset - status fileMoveSucceededJobStatus: type: object title: FileMoveSucceededJobStatus description: Represents the status of a file move succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded asset: $ref: "#/components/schemas/fileAsset" required: - asset - status folderCopySucceededJobStatus: type: object title: FolderCopySucceededJobStatus description: Represents the status of a folder copy succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded asset: $ref: "#/components/schemas/folderAsset" required: - asset - status folderMoveSucceededJobStatus: type: object title: FolderMoveSucceededJobStatus description: Represents the status of a folder move succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded asset: $ref: "#/components/schemas/folderAsset" required: - asset - status brandElementMediaType: type: string title: BrandElementMediaType description: The media type of the brand element. example: application/vnd.adobe.element.image+dcx userId: type: string description: The Unique ID for the user in the system example: 46372D2768435C800A494229@techacct.adobe.com brandElementRole: type: object title: BrandElementRole description: | Describes the role of a brand element within the brand. The fields present depend on the element type: - **Logo** (binary upload): set `usage: logo` and optionally `priority: primary | secondary`. No role → `[]`. - **Graphic** (binary upload): always pass an empty `elementRoles` array — no role object. - **Font** (JSON content): set `usage: header | footer`. No `priority` field. No role → `[]`. - **Color theme** (JSON content): set `priority: primary | secondary`. No `usage` field. No role → `[]`. properties: usage: type: string description: | The usage type for the element. Present for logo and font elements; omitted for color themes and graphics. - `logo` — logo image element (binary upload). - `header` — font element used as a header style. - `body` — font element used as a body style. enum: - logo - header - body example: logo priority: type: string description: | Priority level. Present for logo and color theme elements; omitted for fonts and graphics. Supported values: `primary`, `secondary`. No priority → pass an empty `elementRoles` array. enum: - primary - secondary example: primary brandElement: type: object title: BrandElement description: Represents an element stored within a brand. properties: elementId: type: string description: Unique element identifier. example: urn:aaid:sc:US:brand-element-7f8bc25d-d173-5a62-c48c-2g76fe73b285 name: $ref: "#/components/schemas/assetName" size: $ref: "#/components/schemas/fileSize" mediaType: $ref: "#/components/schemas/brandElementMediaType" createdDate: allOf: - $ref: "#/components/schemas/date" description: ISO 8601 timestamp when the element was created. createdBy: allOf: - $ref: "#/components/schemas/userId" description: User ID of the creator. modifiedDate: allOf: - $ref: "#/components/schemas/date" description: ISO 8601 timestamp when the element was last modified. modifiedBy: allOf: - $ref: "#/components/schemas/userId" description: User ID of the last modifier. elementRoles: type: array description: Roles assigned to the element within the brand. items: $ref: "#/components/schemas/brandElementRole" required: - elementId - name - size - mediaType - createdDate - createdBy - modifiedDate - modifiedBy - elementRoles brandElementFinalizeSucceededJobStatus: type: object title: BrandElementFinalizeSucceededJobStatus description: Represents the status of a brand element finalize succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: succeeded element: $ref: "#/components/schemas/brandElement" required: - element - status succeededJobStatus: description: | Represents the status of a succeeded asynchronous job in the system required: - jobType oneOf: - $ref: "#/components/schemas/fileUploadSucceededJobStatus" - $ref: "#/components/schemas/projectPackageSucceededJobStatus" - $ref: "#/components/schemas/fileDownloadSucceededJobStatus" - $ref: "#/components/schemas/fileCopySucceededJobStatus" - $ref: "#/components/schemas/fileMoveSucceededJobStatus" - $ref: "#/components/schemas/folderCopySucceededJobStatus" - $ref: "#/components/schemas/folderMoveSucceededJobStatus" - $ref: "#/components/schemas/brandElementFinalizeSucceededJobStatus" discriminator: propertyName: jobType mapping: file_upload: "#/components/schemas/fileUploadSucceededJobStatus" project_package: "#/components/schemas/projectPackageSucceededJobStatus" file_download: "#/components/schemas/fileDownloadSucceededJobStatus" file_copy: "#/components/schemas/fileCopySucceededJobStatus" file_move: "#/components/schemas/fileMoveSucceededJobStatus" folder_copy: "#/components/schemas/folderCopySucceededJobStatus" folder_move: "#/components/schemas/folderMoveSucceededJobStatus" brand_element_finalize: "#/components/schemas/brandElementFinalizeSucceededJobStatus" folderCopyPartiallySucceededJobStatus: type: object title: FolderCopyPartiallySucceededJobStatus description: Represents the status of a folder copy partially succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object required: - status - asset - errors properties: status: type: string default: partially_succeeded asset: $ref: "#/components/schemas/folderAsset" errors: type: array description: The errors that occurred during the job items: type: object title: FailedAssetReferenceWithErrorResponse required: - error_code - message - asset allOf: - $ref: "#/components/schemas/errorResponse" - type: object properties: asset: title: FailedAssetReference properties: assetId: allOf: - $ref: "#/components/schemas/assetId" readOnly: true name: type: string description: Human-readable name of the asset example: My Asset assetType: $ref: "#/components/schemas/assetTypeEnums" required: - assetId - name - assetType projectPackagePartiallySucceededJobStatus: type: object title: ProjectPackagePartiallySucceededJobStatus description: Represents the status of a project package partially succeeded asynchronous job in the system allOf: - $ref: "#/components/schemas/baseJobStatus" - type: object properties: status: type: string default: partially_succeeded assets: type: array items: $ref: "#/components/schemas/asset" errors: type: array description: The errors that occurred during the job items: $ref: "#/components/schemas/errorResponse" required: - assets - status - errors partiallySucceededJobStatus: description: | Represents the status of a partially succeeded asynchronous job in the system required: - jobType oneOf: - $ref: "#/components/schemas/folderCopyPartiallySucceededJobStatus" - $ref: "#/components/schemas/projectPackagePartiallySucceededJobStatus" discriminator: propertyName: jobType mapping: folder_copy: "#/components/schemas/folderCopyPartiallySucceededJobStatus" project_package: "#/components/schemas/projectPackagePartiallySucceededJobStatus" 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/partiallySucceededJobStatus" - $ref: "#/components/schemas/failedJobStatus" discriminator: propertyName: status mapping: running: "#/components/schemas/runningJobStatus" succeeded: "#/components/schemas/succeededJobStatus" partially_succeeded: "#/components/schemas/partiallySucceededJobStatus" failed: "#/components/schemas/failedJobStatus" brandElementsListResponse: type: object title: BrandElementsListResponse description: Paginated list of elements inside a brand. properties: items: type: array description: The list of brand elements. items: $ref: "#/components/schemas/brandElement" paging: $ref: "#/components/schemas/pagination" brandElementFinalizeAcceptedResponse: type: object title: BrandElementFinalizeAcceptedResponse description: Represents the accepted response for a brand element finalize asynchronous job properties: jobId: $ref: "#/components/schemas/jobId" required: - jobId brandPermissions: type: object title: BrandPermissions description: The permissions for the user on a brand properties: can_share_brand: type: boolean description: Whether the user can share the brand with other users default: false can_edit_brand: type: boolean description: Whether the user can edit the brand default: false can_view_brand: type: boolean description: Whether the user can view the brand default: false can_delete_brand: type: boolean description: Whether the user can soft delete the brand default: false required: - can_share_brand - can_edit_brand - can_view_brand - can_delete_brand 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 allowReserved: true 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: - `state`: Filter by asset state (operators allowed are `==`). Single value is only supported. - `active` (default): Filter by active assets. - `deleted`: Filter by (soft)deleted assets. - `createdBy`: Filter by project creator (operators allowed are `==` and `!=`). Single value is only supported. - `current_user` is a predefined constant representing the user initiating the request. Currently, this is the sole supported value. --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string examples: All Projects: value: " " Deleted Projects: value: state==deleted Created By Me: value: createdBy==current_user Shared With Me: value: createdBy!=current_user 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" permanent: name: permanent in: query required: false description: | Permanent used for indicating the mode of delete operation. * If true, the operation will do a permanent delete. * If false, the operation will do a soft delete. * If not provided, the default value is false. schema: type: boolean default: false example: true 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 `==` and `=in=`). Multiple values are supported. - `assetType`: Filter by asset type (operators allowed are `==`). Single value is only supported. - `state`: Filter by asset state (operators allowed are `==`). Single value is only supported. - `active` (default): Filter by active assets. - `deleted`: Filter by (soft)deleted assets. --- > NOTE: > * Only applicable for the first page. Subsequent pages must use the cursor. --- schema: type: string examples: All Assets: value: "" Files: value: assetType==file Folders: value: assetType==folder Deleted Assets: value: state==deleted PNG Images: value: mediaType==image/png 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: * The server may adjust it to enforce internal limits. * 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 minimum: 1 maximum: 8192 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: $ref: "#/components/schemas/requestId" 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 unauthorized: description: | **Unauthorized** - The request is unauthorized. value: error_code: unauthorized message: You are not authorized to access this resource. notAcceptable: description: | **Not Acceptable** - The requested representation is not acceptable value: error_code: not_acceptable message: The requested representation is not acceptable. invalidLimitType: description: | **Mismatch Parameter Type** - Provided value of limit parameter is not compatible with the expected type value: error_code: validation_error message: "Provided value: (abc) for query parameter: limit is of invalid type. Allowed Type is Integer" invalidLimitRange: description: | **Invalid Range** - Provided value of limit parameter is out of the allowed range value: error_code: validation_error message: "Provided value: (1000) for query parameter: limit is out of the allowed range. Allowed Range is 1-100" invalidPaginationParameterCombination: description: | **Invalid Combination** - Combination of pagination parameters is invalid value: error_code: validation_error message: "Following query parameters: [cursor and sortBy] are not allowed together" multipleInvalidRequestViolations: description: | **Multiple Violations** - Multiple problems with the request value: error_code: validation_error 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 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. 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. 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 invalidRequestBody: description: | **Bad Request Body** - The server cannot proceed because the request body is not valid JSON value: error_code: bad_request message: The provided request body is not a valid JSON missingRequestBody: description: | **Missing Request Body** - The server cannot proceed because the request body is missing value: error_code: bad_request message: The request is missing the required body 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. invalidOperation: description: | **Invalid Operation** - The requested operation is invalid based on the current state of the resource value: error_code: invalid_operation message: The operation is invalid as it resulted in a conflict or is not allowed. 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. 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) invalidNameType: description: | **Invalid Name Type** - The server cannot proceed because the name is of invalid type value: error_code: validation_error message: The provided name has an invalid type. invalidNameValue: description: | **Invalid Name Value** - The server cannot proceed because the name is invalid value: error_code: validation_error message: The provided name has an invalid value. invalidAssetIdValue: description: | **Invalid AssetId Value** - The server cannot proceed because the assetId is invalid value: error_code: validation_error message: The provided assetId has an invalid value. 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]." 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. etagMismatch: description: | **Precondition Failed** - The request failed due to a precondition value: error_code: etag_mismatch message: Expected etag is different for the current. operationTimedOut: description: | **Operation Timed Out** - The server failed to complete the operation within 60 seconds. value: error_code: operation_timeout message: The operation is taking longer than 60 seconds. The operation is still in progress and will be completed soon. storageQuotaExceeded: description: | **Storage Quota Exceeded** - The user has exceeded their storage quota value: error_code: storage_quota_exceeded message: Your quota has been exceeded. Please try later after cleanup or contact support. 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 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 mediaType: image/png size: 2418293 state: active 200.assetRoles: description: | **Asset Roles** - The roles 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 patchAssetRoles: 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. 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 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. invalidUploadIdType: description: | **Invalid UploadId Type** - The server cannot proceed because the uploadId is of invalid type value: error_code: validation_error message: The provided uploadId has an invalid type. invalidUsedTransferLinksValue: description: | **Invalid UsedTransferLinks Value** - The server cannot proceed because the usedTransferLinks value is invalid value: error_code: validation_error message: The provided usedTransferLinks value is invalid. expiredOrAlreadyUsed: description: | **Invalid Operation** - Upload has either expired or has already been finalized value: error_code: invalid_operation message: Upload has either expired or has already been finalized. singleBrand: value: assetId: urn:aaid:sc:US:7f8bc25d-d173-5a62-c48c-2g76fe73b285 name: My Brand createdDate: "2026-02-23T14:00:00Z" modifiedDate: "2026-02-23T14:00:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /My Project/My Brand ancestors: - urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 state: active assetType: brand mediaType: application/vnd.adobe.library+dcx elementsCount: 0 size: 0 renameBrand: value: assetId: urn:aaid:sc:US:7f8bc25d-d173-5a62-c48c-2g76fe73b285 name: My Brand createdDate: "2026-02-23T14:00:00Z" modifiedDate: "2026-02-23T14:00:00Z" createdBy: 08D81E3B665BE5640A495C2C@AdobeOrg modifiedBy: 08D81E3B665BE5640A495C2C@AdobeOrg path: /My Project/My Brand state: active assetType: brand mediaType: application/vnd.adobe.library+dcx elementsCount: 0 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" notAcceptableResponse: description: | **Not Acceptable** - The requested representation is not acceptable headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: notAcceptable: $ref: "#/components/examples/notAcceptable" invalidRequestPagedResponse: description: | **Unprocessable Request** - The server cannot process the request due to a semantic 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" 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" invalidRequestResponse: 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: invalidRequestBody: $ref: "#/components/examples/invalidRequestBody" missingRequestBody: $ref: "#/components/examples/missingRequestBody" 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" 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" 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" unprocessableEntityResponse: description: | **Unprocessable Request** - 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" invalidNameType: $ref: "#/components/examples/invalidNameType" invalidNameValue: $ref: "#/components/examples/invalidNameValue" invalidAssetIdValue: $ref: "#/components/examples/invalidAssetIdValue" 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" 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: etagMismatch: $ref: "#/components/examples/etagMismatch" storageQuotaExceededResponse: description: | **Insufficient Storage** - The request cannot be processed because the storage quota has been exceeded headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" examples: storageQuotaExceeded: $ref: "#/components/examples/storageQuotaExceeded" 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" content: application/json: schema: $ref: "#/components/schemas/paginatedAssets" examples: paginatedAssets: $ref: "#/components/examples/paginatedAssets" projectPermissionResponse: description: | **Success** - Effective permission for the user for a project asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: ProjectEffectivePermissionResponse description: The effective permission for the user for a project asset properties: role: $ref: "#/components/schemas/roleEnums" deprecated: true permissions: $ref: "#/components/schemas/projectPermissions" required: - permissions examples: Project's Effective Permissions: value: role: edit permissions: can_edit_project: true can_view_project: true can_share: true can_comment: true can_restore: false can_delete: false can_permanent_delete: false can_download_assets: true can_move_assets_inside: true can_move_assets_outside: false getAssetRolesResponse: description: | **Success** - A list of collaborators and their roles for the asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/assetRolesResponse" examples: All Roles: $ref: "#/components/examples/200.assetRoles" patchAssetRolesResponse: description: | **Success/Partial Success** Patching the roles 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/patchAssetRolesResponse" 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 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" folderPermissionResponse: description: | **Success** - Effective permission for the user for a folder asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: FolderEffectivePermissionResponse description: The effective permission for the user for a folder asset properties: role: $ref: "#/components/schemas/roleEnums" deprecated: true permissions: $ref: "#/components/schemas/folderPermissions" required: - permissions examples: Folder's Effective Permissions: value: role: edit permissions: can_edit_assets: true can_view_assets: true can_share: true can_comment: true can_restore_assets: false can_delete_assets: false can_permanent_delete_assets: false can_download_assets: true can_move_assets_inside: true can_move_assets_outside: false filePermissionResponse: description: | **Success** - Effective permission for the user for a file asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: FileEffectivePermissionResponse description: The effective permission for the user for a file asset properties: role: $ref: "#/components/schemas/roleEnums" deprecated: true permissions: $ref: "#/components/schemas/filePermissions" required: - permissions examples: File's Effective Permissions: value: role: edit permissions: can_edit_assets: true can_view_assets: true can_share: true can_comment: true can_restore_assets: false can_delete_assets: false can_permanent_delete_assets: false can_download_assets: true fileCopyAcceptedResponse: description: | **Accepted** - Request to copy a file was accepted and will be processed asynchronously. headers: x-request-id: $ref: "#/components/headers/requestId" retry-after: $ref: "#/components/headers/retryAfter" content: application/json: schema: type: object title: FileCopyAcceptedResponse description: Asynchronous job id used to call the status endpoint. properties: jobId: $ref: "#/components/schemas/jobId" examples: File Copy Accepted: value: jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9 fileMoveAcceptedResponse: description: | **Accepted** - Request to move a file was accepted and will be processed asynchronously. headers: x-request-id: $ref: "#/components/headers/requestId" retry-after: $ref: "#/components/headers/retryAfter" content: application/json: schema: type: object title: FileMoveAcceptedResponse description: Asynchronous job id used to call the status endpoint. properties: jobId: $ref: "#/components/schemas/jobId" examples: File Move Accepted: value: jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9 contentTypeChangeNotAllowedResponse: description: | **Unsupported Media Type** - Content type cannot be changed from original file type. headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/errorResponse" fileDownloadOKResponse: description: | **Success** - A pre-signed download URL for the asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: $ref: "#/components/schemas/fileDownloadOKResponse" fileDownloadAcceptedResponse: description: | **Accepted** - 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: FileDownloadAcceptedResponse 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: downloadAcceptedResponse: value: jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9 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 brandEffectivePermissionResponse: description: | **Success** - Effective permission for the user for a brand asset headers: x-request-id: $ref: "#/components/headers/requestId" content: application/json: schema: type: object title: BrandEffectivePermissionResponse description: The effective permission for the user for a brand asset properties: role: $ref: "#/components/schemas/roleEnums" deprecated: true permissions: $ref: "#/components/schemas/brandPermissions" required: - permissions examples: Brand's Effective Permissions: value: role: edit permissions: can_edit_brand: true can_view_brand: true can_share_brand: true can_delete_brand: false 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" options: $ref: "#/components/schemas/operationOptions" projectRenameRequest: required: true content: application/json: schema: type: object title: ProjectRenameRequest description: Represents a request body for renaming a project. nullable: false required: - name properties: name: $ref: "#/components/schemas/assetName" options: $ref: "#/components/schemas/operationOptions" patchAssetRoles: required: true content: application/json: schema: $ref: "#/components/schemas/patchAssetRolesRequest" examples: patchPermissions: $ref: "#/components/examples/patchAssetRoles" 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" options: $ref: "#/components/schemas/operationOptions" 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 folderRenameRequest: required: true content: application/json: schema: type: object title: FolderRenameRequest description: | Represents a request body for renaming a folder. nullable: false properties: name: $ref: "#/components/schemas/assetName" options: $ref: "#/components/schemas/operationOptions" required: - name fileRenameRequest: required: true content: application/json: schema: type: object title: FileRenameRequest description: | Represents a request body for renaming a file. nullable: false properties: name: $ref: "#/components/schemas/assetName" options: $ref: "#/components/schemas/operationOptions" required: - name fileCopyRequest: required: true content: application/json: schema: $ref: "#/components/schemas/copyRequest" examples: Copy Request With New Name: value: name: Renamed File.png parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a Copy Request With Original Name: value: parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a Copy Request with autorename: value: parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a options: autorename: true fileMoveRequest: required: true content: application/json: schema: $ref: "#/components/schemas/moveRequest" examples: Move Request With New Name: value: name: Renamed File.png parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a Move Request With Original Name: value: parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a Move Request with autorename: value: parentId: urn:aaid:sc:US:f860f2fc-7942-4e49-ab37-5e2b32afe97a options: autorename: true 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: allOf: - $ref: "#/components/schemas/assetId" description: Asset Id of the parent container (project/folder). 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 options: $ref: "#/components/schemas/operationOptions" 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 fileReplaceInitRequest: required: true content: application/json: schema: type: object title: FileReplacementUploadInitRequest description: | This request body is used to initialize a block based file replacement upload job. properties: size: $ref: "#/components/schemas/fileSize" 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 options: $ref: "#/components/schemas/operationOptions" required: - size - mediaType brandCreateRequest: required: true content: application/json: schema: type: object title: BrandCreateRequest description: Represents a request body for creating a brand. nullable: false required: - name - parentId properties: name: $ref: "#/components/schemas/assetName" parentId: $ref: "#/components/schemas/assetId" examples: createBrand: summary: Create a new brand value: name: My Brand parentId: urn:aaid:sc:US:4f2fc15c-c062-4951-b37b-1f65ed62a174 brandRenameRequest: required: true content: application/json: schema: type: object title: BrandRenameRequest description: | Represents a request body for renaming a brand. nullable: false properties: name: $ref: "#/components/schemas/assetName" required: - name brandElementUploadInitRequest: required: true content: application/json: schema: type: object title: BrandElementUploadInitRequest description: | This request body is used to initialize a block-based upload for a new binary brand element. properties: name: $ref: "#/components/schemas/assetName" size: $ref: "#/components/schemas/fileSize" mediaType: $ref: "#/components/schemas/brandElementMediaType" blockSize: type: integer description: The size of each block in bytes. The block size returned may differ from the size requested. example: 1048576 elementRoles: type: array description: | Roles assigned to the element within the brand. - **Logo elements**: set `usage: logo` with optional `priority: primary | secondary`. Pass `[]` for no priority. - **Graphic elements**: always pass `[]` — graphics carry no role. items: $ref: "#/components/schemas/brandElementRole" required: - name - size - mediaType brandElementUploadFinalizeRequest: required: true content: application/json: schema: type: object title: BrandElementUploadFinalizeRequest description: | This request body is used to finalize a block-based upload for a brand element. properties: uploadId: type: string description: Upload session ID from the init response. example: 123e4567-e89b-12d3-a456-426614174000 usedTransferLinks: type: array description: The part numbers of the transfer links used for uploading the content. 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 - 2 brandElementContentRequest: required: true content: multipart/form-data: schema: type: object properties: metadata: type: object title: BrandElementContentMetadata description: | JSON metadata for the brand element being created. properties: name: $ref: "#/components/schemas/assetName" description: type: string description: Optional description for the brand element. example: Primary brand font elementRoles: type: array description: | Roles assigned to the element within the brand. - **Font elements**: set `usage: header | body`. No `priority` field. Pass `[]` for no role. - **Color theme elements**: set `priority: primary | secondary`. No `usage` field. Pass `[]` for no role. items: $ref: "#/components/schemas/brandElementRole" required: - name data: type: string format: binary description: | The JSON content of the brand element. The `Content-Type` header of this part determines the element's media type. Supported types: - `application/vnd.adobe.element.colortheme+dcx` — color palette. Body must be a JSON object with `mood` (string) and `swatches` (array of swatch arrays). A minimum of 2 swatches is required. Each swatch is an array of color stop objects with `mode`, `value` (`r`, `g`, `b`), and `alpha` fields. - `application/vnd.adobe.element.font+dcx` — font definition. required: - metadata - data encoding: metadata: contentType: application/json data: contentType: application/vnd.adobe.element.font+dcx, application/vnd.adobe.element.colortheme+dcx