---
title: "Update file details"
method: PATCH
path: "/v1/files/{fileId}/details"
tags: ["Digital Asset Management (DAM)", "Managing assets"]
---

# Update file details

`PATCH /v1/files/{fileId}/details`

This API updates the details or attributes of the current version of the file. You can update `tags`, `customCoordinates`, `customMetadata`, publication status, remove existing `AITags` and apply extensions using this API.

## Path parameters

- `fileId` string, required

## Request body

- union — Schema for update file update request.
  - object
    - `removeAITags` union — An array of AITags associated with the file that you want to remove, e.g. `["car", "vehicle", "motorsports"]`. If you want to remove all AITags associated with the file, send a string - "all". Note: The remove operation for `AITags` executes before any of the `extensions` are processed.
      - string[]
      - 'all'
    - `webhookUrl` string, uri — The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure) about the webhook payload structure.
    - `extensions` union[] — Array of extensions to be applied to the asset. Each extension can be configured with specific parameters based on the extension type.
      - union
        - RemovedotBGExtension
          - `name` 'remove-bg', required — Specifies the background removal extension.
          - `options` object
            - `add_shadow` boolean — Whether to add an artificial shadow to the result. Default is false. Note: Adding shadows is currently only supported for car photos.
            - `semitransparency` boolean — Allows semi-transparent regions in the result. Default is true. Note: Semitransparency is currently only supported for car windows.
            - `bg_color` string — Specifies a solid color background using hex code (e.g., "81d4fa", "fff") or color name (e.g., "green"). If this parameter is set, `bg_image_url` must be empty.
            - `bg_image_url` string — Sets a background image from a URL. If this parameter is set, `bg_color` must be empty.
        - AutoTaggingExtension
          - `name` 'google-auto-tagging' | 'aws-auto-tagging', required — Specifies the auto-tagging extension used.
          - `minConfidence` integer, required — Minimum confidence level for tags to be considered valid.
          - `maxTags` integer, required — Maximum number of tags to attach to the asset.
        - AutoDescriptionExtension
          - `name` 'ai-auto-description', required — Specifies the auto description extension.
        - AITasksExtension
          - `name` 'ai-tasks', required — Specifies the AI tasks extension for automated image analysis using AI models.
          - `tasks` union[], required — Array of task objects defining AI operations to perform on the asset.
            - union
              - …
        - SavedExtensionReference
          - `name` 'saved-extension', required — Indicates this is a reference to a saved extension.
          - `id` string, required — The unique ID of the saved extension to apply.
    - `tags` union — An array of tags associated with the file, such as `["tag1", "tag2"]`. Send `null` to unset all tags associated with the file.
      - string[]
      - string[]
    - `customCoordinates` union — Define an important area in the image in the format `x,y,width,height` e.g. `10,10,100,100`. Send `null` to unset this value.
      - string
      - unknown
    - `customMetadata` object — A key-value data to be associated with the asset. To unset a key, send `null` value for that key. Before setting any custom metadata on an asset you have to create the field using custom metadata fields API.
    - `description` string — Optional text to describe the contents of the file.
  - object
    - `publish` object — Configure the publication status of a file and its versions.
      - `isPublished` boolean, required — Set to `true` to publish the file. Set to `false` to unpublish the file.
      - `includeFileVersions` boolean — Set to `true` to publish/unpublish all versions of the file. Set to `false` to publish/unpublish only the current version of the file.

## Response `200`

Updated file details object.

- object — Object containing details of a file or file version.
  - `fileId` string — Unique identifier of the asset.
  - `type` 'file' | 'file-version' — Type of the asset.
  - `name` string — Name of the asset.
  - `filePath` string — Path of the file. This is the path you would use in the URL to access the file. For example, if the file is at the root of the media library, the path will be `/file.jpg`. If the file is inside a folder named `images`, the path will be `/images/file.jpg`.
  - `tags` union — An array of tags assigned to the file. Tags are used to search files in the media library.
    - string[]
    - string[]
  - `AITags` union — Array of AI-generated tags associated with the image. If no AITags are set, it will be null.
    - AITag[]
      - `name` string — Name of the tag.
      - `confidence` number — Confidence score of the tag.
      - `source` string — Source of the tag. Possible values are `google-auto-tagging` and `aws-auto-tagging`.
    - AITag[]
      - `name` string — Name of the tag.
      - `confidence` number — Confidence score of the tag.
      - `source` string — Source of the tag. Possible values are `google-auto-tagging` and `aws-auto-tagging`.
  - `versionInfo` VersionInfo — An object containing the file or file version's `id` (versionId) and `name`.
    - `id` string — Unique identifier of the file version.
    - `name` string — Name of the file version.
  - `isPrivateFile` boolean — Specifies if the file is private or not.
  - `isPublished` boolean — Specifies if the file is published or not.
  - `customCoordinates` union — An string with custom coordinates of the file.
    - string
    - unknown
  - `url` string, uri — URL of the file.
  - `thumbnail` string, uri — URL of the thumbnail image. This URL is used to access the thumbnail image of the file in the media library.
  - `fileType` string — Type of the file. Possible values are `image`, `non-image`.
  - `mime` string — MIME type of the file.
  - `width` number — Width of the file.
  - `height` number — Height of the file.
  - `size` number — Size of the file in bytes.
  - `bitRate` integer — The bit rate of the video in kbps (only for video).
  - `duration` integer — The duration of the video in seconds (only for video).
  - `audioCodec` string — The audio codec used in the video (only for video/audio).
  - `videoCodec` string — The video codec used in the video (only for video).
  - `hasAlpha` boolean — Specifies if the image has an alpha channel.
  - `customMetadata` CustomMetadata — A key-value data associated with the asset.
  - `selectedFieldsSchema` SelectedFieldsSchema — This field is included in the response only if the Path policy feature is available in the plan. It contains schema definitions for the custom metadata fields selected for the specified file path. Field selection can only be done when the Path policy feature is enabled. Keys are the names of the custom metadata fields; the value object has details about the custom metadata schema.
  - `embeddedMetadata` EmbeddedMetadata — Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data.
  - `description` string — Optional text to describe the contents of the file. Can be set by the user or the ai-auto-description extension.
  - `createdAt` string, date-time — Date and time when the file was uploaded. The date and time is in ISO8601 format.
  - `updatedAt` string, date-time — Date and time when the file was last updated. The date and time is in ISO8601 format.
  - `extensionStatus` object
    - `google-auto-tagging` 'success' | 'pending' | 'failed'
    - `aws-auto-tagging` 'success' | 'pending' | 'failed'
    - `remove-bg` 'success' | 'pending' | 'failed'
    - `ai-auto-description` 'success' | 'pending' | 'failed'
    - `ai-tasks` 'success' | 'pending' | 'failed'

## Other responses

- `400` — Bad request.
- `401` — Unauthorized request.
- `403` — Forbidden.
- `404` — File not found.
- `429` — The request exceeded the rate limit. Contains headers indicating the limits and a message detailing the error.

---

[API](https://skmtc.dev/imagekit-developer/apis/imagekit-api.md) · [All operations](https://skmtc.dev/imagekit-developer/apis/imagekit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/imagekit-developer/imagekit-api/revisions/bb3e9ff84b3e/schema)