ImageKit Digital Asset Management (DAM) API
The Digital Asset Management (DAM) API from ImageKit — 22 operation(s) for digital asset management (dam).
OpenAPI Specification
openapi: 3.0.3
info:
title: ImageKit Account Management API Digital Asset Management (DAM) API
version: 1.0.0
description: Checkout [API overview](/docs/api-overview) to learn about ImageKit's APIs, authentication, rate limits, and error codes etc.
contact:
email: developer@imagekit.io
name: ImageKit Team
url: https://imagekit.io
termsOfService: https://imagekit.io/terms/
servers:
- url: https://api.imagekit.io
security:
- basicAuth: []
tags:
- name: Digital Asset Management (DAM)
paths:
/v1/customMetadataFields:
post:
summary: Create new field
operationId: create-new-field
description: 'This API creates a new custom metadata field. Once a custom metadata field is created either through this API or using the dashboard UI, its value can be set on the assets. The value of a field for an asset can be set using the media library UI or programmatically through upload or update assets API.
'
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- label
- schema
properties:
name:
type: string
description: API name of the custom metadata field. This should be unique across all (including deleted) custom metadata fields.
label:
type: string
description: Human readable name of the custom metadata field. This should be unique across all non deleted custom metadata fields. This name is displayed as form field label to the users while setting field value on an asset in the media library UI.
schema:
type: object
required:
- type
properties:
type:
description: Type of the custom metadata field.
type: string
enum:
- Text
- Textarea
- Number
- Date
- Boolean
- SingleSelect
- MultiSelect
selectOptions:
type: array
items:
oneOf:
- type: string
- type: number
- type: boolean
description: 'An array of allowed values. This property is only required if `type` property is set to `SingleSelect` or `MultiSelect`.
'
example:
- small
- medium
- large
- 30
- 40
- true
defaultValue:
description: 'The default value for this custom metadata field. This property is only required if `isValueRequired` property is set to `true`. The value should match the `type` of custom metadata field.
'
oneOf:
- type: string
- type: number
- type: boolean
- type: array
x-stainless-variantName: Mixed
title: Mixed
items:
title: Default value item
oneOf:
- type: string
- type: number
- type: boolean
description: 'Default value should be of type array when custom metadata field type is set to `MultiSelect`.
'
example:
- true
- 10
- Hello
isValueRequired:
type: boolean
description: 'Sets this custom metadata field as required. Setting custom metadata fields on an asset will throw error if the value for all required fields are not present in upload or update asset API request body.
'
minValue:
description: 'Minimum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value.
'
oneOf:
- type: string
- type: number
maxValue:
description: 'Maximum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value.
'
oneOf:
- type: string
- type: number
minLength:
description: 'Minimum length of string. Only set this property if `type` is set to `Text` or `Textarea`.
'
type: number
maxLength:
description: 'Maximum length of string. Only set this property if `type` is set to `Text` or `Textarea`.
'
type: number
example:
name: price
label: price
schema:
type: Number
minValue: 1000
maxValue: 3000
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'201':
description: Custom metadata field created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomMetadataField'
example:
id: 598821f949c0a938d57563dd
name: price
label: price
schema:
type: Number
minValue: 1000
maxValue: 3000
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: A custom metadata field with this name already exists.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
tags:
- Digital Asset Management (DAM)
get:
tags:
- Digital Asset Management (DAM)
operationId: list-all-fields
summary: List all fields
description: 'This API returns the array of created custom metadata field objects. By default the API returns only non deleted field objects, but you can include deleted fields in the API response.
You can also filter results by a specific folder path to retrieve custom metadata fields applicable at that location. This path-specific filtering is useful when using the **Path policy** feature to determine which custom metadata fields are selected for a given path.
'
parameters:
- in: query
description: 'Set it to `true` to include deleted field objects in the API response.
'
name: includeDeleted
required: false
schema:
type: boolean
default: false
- in: query
description: 'The folder path (e.g., `/path/to/folder`) for which to retrieve applicable custom metadata fields. Useful for determining path-specific field selections when the [Path policy](https://imagekit.io/docs/dam/path-policy) feature is in use.
'
name: folderPath
required: false
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: Array of custom metadata field objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomMetadataField'
example:
- id: 598821f949c0a938d57563dd
name: brand
label: brand
schema:
type: Text
defaultValue: Nike
- id: 865421f949c0a835d57563dd
name: price
label: price
schema:
type: Number
minValue: 1000
maxValue: 3000
/v1/files/{fileId}/details:
get:
tags:
- Digital Asset Management (DAM)
operationId: get-file-details
summary: Get file details
description: This API returns an object with details or attributes about the current version of the file.
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in the list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: File details object.
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetails'
example:
fileId: 598821f949c0a938d57563bd
type: file
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 1
isPrivateFile: false
isPublished: true
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
description: A product description
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
patch:
tags:
- Digital Asset Management (DAM)
operationId: update-file-details
summary: Update file details
description: '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.
'
parameters:
- description: 'The unique `fileId` of the uploaded file. `fileId` is returned in list and search assets API and upload API.
'
in: path
name: fileId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFileRequest'
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: Updated file details object.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/FileDetails'
- type: object
properties:
extensionStatus:
type: object
properties:
google-auto-tagging:
type: string
enum:
- success
- pending
- failed
aws-auto-tagging:
type: string
enum:
- success
- pending
- failed
remove-bg:
type: string
enum:
- success
- pending
- failed
ai-auto-description:
type: string
enum:
- success
- pending
- failed
ai-tasks:
type: string
enum:
- success
- pending
- failed
example:
fileId: 598821f949c0a938d57563bd
type: file
name: file1.jpg
filePath: /images/products/file.jpg
isPublished: true
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 1
isPrivateFile: false
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
extensionStatus:
google-auto-tagging: success
remove-bg: pending
ai-auto-description: success
ai-tasks: success
'404':
description: File not found.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The requested file does not exist.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Invalid custom metadata.
- Your request contains invalid fileId parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
errors:
type: object
/v1/customMetadataFields/{id}:
patch:
tags:
- Digital Asset Management (DAM)
operationId: update-existing-field
summary: Update existing field
description: 'This API updates the label or schema of an existing custom metadata field.
'
parameters:
- description: 'Should be a valid custom metadata field id.
'
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
label:
type: string
description: Human readable name of the custom metadata field. This should be unique across all non deleted custom metadata fields. This name is displayed as form field label to the users while setting field value on an asset in the media library UI. This parameter is required if `schema` is not provided.
schema:
type: object
description: 'An object that describes the rules for the custom metadata key. This parameter is required if `label` is not provided. Note: `type` cannot be updated and will be ignored if sent with the `schema`. The schema will be validated as per the existing `type`.
'
properties:
selectOptions:
type: array
items:
oneOf:
- type: string
- type: number
- type: boolean
description: 'An array of allowed values. This property is only required if `type` property is set to `SingleSelect` or `MultiSelect`.
'
example:
- small
- medium
- large
- 30
- 40
- true
defaultValue:
description: 'The default value for this custom metadata field. This property is only required if `isValueRequired` property is set to `true`. The value should match the `type` of custom metadata field.
'
oneOf:
- type: string
- type: number
- type: boolean
- type: array
x-stainless-variantName: Mixed
title: Mixed
items:
title: Default value item
oneOf:
- type: string
- type: number
- type: boolean
description: 'Default value should be of type array when custom metadata field type is set to `MultiSelect`.
'
example:
- true
- 10
- Hello
isValueRequired:
type: boolean
description: 'Sets this custom metadata field as required. Setting custom metadata fields on an asset will throw error if the value for all required fields are not present in upload or update asset API request body.
'
minValue:
description: 'Minimum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value.
'
oneOf:
- type: string
- type: number
maxValue:
description: 'Maximum value of the field. Only set this property if field type is `Date` or `Number`. For `Date` type field, set the minimum date in ISO8601 string format. For `Number` type field, set the minimum numeric value.
'
oneOf:
- type: string
- type: number
minLength:
description: 'Minimum length of string. Only set this property if `type` is set to `Text` or `Textarea`.
'
type: number
maxLength:
description: 'Maximum length of string. Only set this property if `type` is set to `Text` or `Textarea`.
'
type: number
example:
label: price
schema:
type: Number
minValue: 1000
maxValue: 3000
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Cannot update a deleted custom metadata fields.
- Either label or schema should be provided.
- A custom metadata field with this label already exists.
- Invalid schema object.
- Name cannot be updated.
- Missing id parameter.
- Your request contains invalid ID parameter.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'404':
description: Custom metadata field doesn't exist.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: No such custom metadata field exists.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'200':
description: Custom metadata field updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomMetadataField'
example:
id: 598821f949c0a938d57563dd
name: price
label: price
schema:
type: Number
minValue: 1000
maxValue: 3000
delete:
tags:
- Digital Asset Management (DAM)
operationId: delete-a-field
summary: Delete a field
description: 'This API deletes a custom metadata field. Even after deleting a custom metadata field, you cannot create any new custom metadata field with the same name.
'
parameters:
- description: 'Should be a valid custom metadata field id.
'
in: path
name: id
required: true
schema:
type: string
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Missing id parameter.
- Your request contains invalid ID parameter.
- 'This custom metadata field cannot be deleted as it is a part of a path policy: policy-name'
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'404':
description: Custom metadata field doesn't exist.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: No such custom metadata field exists.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
'204':
description: Custom metadata field deleted successfully.
content:
application/json:
schema:
type: object
x-stainless-empty-object: true
/v1/files:
get:
tags:
- Digital Asset Management (DAM)
operationId: list-and-search-assets
summary: List and search assets
description: 'This API can list all the uploaded files and folders in your ImageKit.io media library. In addition, you can fine-tune your query by specifying various filters by generating a query string in a Lucene-like syntax and provide this generated string as the value of the `searchQuery`.
'
parameters:
- in: query
name: type
required: false
description: "Filter results by asset type.\n\n- `file` — returns only files \n- `file-version` — returns specific file versions \n- `folder` — returns only folders \n- `all` — returns both files and folders (excludes `file-version`)\n"
schema:
type: string
enum:
- file
- file-version
- folder
- all
default: file
- in: query
name: sort
required: false
description: 'Sort the results by one of the supported fields in ascending or descending order.
'
schema:
type: string
enum:
- ASC_NAME
- DESC_NAME
- ASC_CREATED
- DESC_CREATED
- ASC_UPDATED
- DESC_UPDATED
- ASC_HEIGHT
- DESC_HEIGHT
- ASC_WIDTH
- DESC_WIDTH
- ASC_SIZE
- DESC_SIZE
- ASC_RELEVANCE
- DESC_RELEVANCE
default: ASC_CREATED
- in: query
name: path
required: false
description: 'Folder path if you want to limit the search within a specific folder. For example, `/sales-banner/` will only search in folder sales-banner.
Note : If your use case involves searching within a folder as well as its subfolders, you can use `path` parameter in `searchQuery` with appropriate operator.
Checkout [Supported parameters](/docs/api-reference/digital-asset-management-dam/list-and-search-assets#supported-parameters) for more information.
'
schema:
type: string
- in: query
name: searchQuery
required: false
description: 'Query string in a Lucene-like query language e.g. `createdAt > "7d"`.
Note : When the searchQuery parameter is present, the following query parameters will have no effect on the result:
1. `tags`
2. `type`
3. `name`
[Learn more](/docs/api-reference/digital-asset-management-dam/list-and-search-assets#advanced-search-queries) from examples.
'
schema:
type: string
- in: query
name: fileType
required: false
description: "Filter results by file type.\n\n- `all` — include all file types \n- `image` — include only image files \n- `non-image` — include only non-image files (e.g., JS, CSS, video)\n"
schema:
type: string
enum:
- all
- image
- non-image
default: all
- in: query
name: limit
required: false
description: 'The maximum number of results to return in response.
'
schema:
type: integer
minimum: 1
maximum: 1000
default: 1000
- in: query
name: skip
required: false
description: 'The number of results to skip before returning results.
'
schema:
type: integer
minimum: 0
default: 0
responses:
'429':
$ref: '#/components/responses/RateLimitExceeded'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: List of assets.
content:
application/json:
schema:
type: array
items:
discriminator:
propertyName: type
mapping:
file: '#/components/schemas/FileDetails'
file-version: '#/components/schemas/FileDetails'
folder: '#/components/schemas/FolderDetails'
oneOf:
- $ref: '#/components/schemas/FileDetails'
- $ref: '#/components/schemas/FolderDetails'
example:
- fileId: 598821f949c0a938d57563bd
type: file
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- round-neck
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
id: 598821f949c0a938d57563bd
name: Version 2
isPrivateFile: false
customCoordinates: null
url: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313
thumbnail: https://ik.imagekit.io/your_imagekit_id/images/products/file.jpg?updatedAt=1566630881313&tr=n-ik_ml_thumbnail
fileType: image
mime: image/jpeg
width: 100
height: 100
size: 100
hasAlpha: false
customMetadata:
brand: Nike
color: red
createdAt: '2019-08-24T06:14:41.313Z'
updatedAt: '2019-08-24T06:14:41.313Z'
- fileId: 598821f949c0a938d81963bd
type: file-version
name: file.jpg
filePath: /images/products/file.jpg
tags:
- t-shirt
- sale2019
AITags:
- name: Shirt
confidence: 90.12
source: google-auto-tagging
- name: T-shirt
confidence: 80.12
source: aws-auto-tagging
versionInfo:
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-json-v1-9-imagekit/refs/heads/main/openapi/imagekit-digital-asset-management-dam-api-openapi.yml