From 5e8f394a9b460af33277414d0e30db54c404d8e6 Mon Sep 17 00:00:00 2001 From: Harshit Budhraja Date: Tue, 28 Jul 2026 11:36:10 +0530 Subject: [PATCH 1/3] feat(api): add named transformations endpoints for listing, creating, retrieving, and updating transformations - Introduced new endpoints for managing named transformations, including GET, POST, and PATCH methods. - Added detailed descriptions and response schemas for each endpoint in the OpenAPI specification. - Updated the stainless configuration to include named transformations resources. --- openapi/v1.0.0.yaml | 399 +++++++++++++++++++++++++++++++++++++ stainless-config/main.yaml | 10 + 2 files changed, 409 insertions(+) diff --git a/openapi/v1.0.0.yaml b/openapi/v1.0.0.yaml index b2af725..4572fdc 100644 --- a/openapi/v1.0.0.yaml +++ b/openapi/v1.0.0.yaml @@ -4103,6 +4103,294 @@ paths: "403": *a2 "429": *a3 + /v1/named-transformations: + get: + summary: List named transformations + tags: + - Account Management API + - Named Transformations + operationId: list-named-transformations + description: | + Returns an array of all named transformations configured for your account, including the account's default named transformation (`ik_ml_thumbnail`), which is used internally to generate media library thumbnails. + + **Note:** Use the `includeDefault` query parameter to exclude the account's default named transformation (`ik_ml_thumbnail`) from the response. + parameters: + - in: query + name: includeDefault + required: false + description: | + Set to `false` to exclude the account's default named transformation (`ik_ml_thumbnail`) from the response. + schema: + type: boolean + default: true + responses: + "200": + description: Array of named transformation objects. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/NamedTransformation" + example: + - id: "ik_ml_thumbnail" + name: "ik_ml_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-pad_resize" + disabled: false + isDefault: true + createdAt: "2019-10-03T15:22:28.297Z" + - id: "6bZ9x2ZUx" + name: "small_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-resize" + disabled: false + isDefault: false + createdAt: "2024-01-10T09:00:00.000Z" + "401": *a1 + "403": *a2 + "429": *a3 + post: + summary: Create named transformation + tags: + - Account Management API + - Named Transformations + operationId: create-named-transformation + description: | + Creates a new named transformation and returns the created object. + + Named transformations let you assign a short, reusable name to a complex transformation string, so it can be applied in image and video URLs as `tr:n-` and later updated without changing any existing URLs. + + Learn more about [named transformations](https://imagekit.io/docs/transformations#named-transformations). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateNamedTransformation" + example: + name: "small_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-resize" + disabled: false + responses: + "201": + description: Named transformation created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/NamedTransformation" + example: + id: "6bZ9x2ZUx" + name: "small_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-resize" + disabled: false + isDefault: false + createdAt: "2024-01-10T09:00:00.000Z" + "400": + description: Bad request. The request body failed validation. + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - "`name` is required and may contain only alphanumeric characters, '_' or '-'." + - "\"ik_ml_thumbnail\" is reserved for the default named transformation and cannot be used." + - "`transformation` is required and must start with 'tr:'." + help: + type: string + example: For support kindly contact us at support@imagekit.io. + "409": &a7 + description: A named transformation with this name already exists. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: "A named transformation with the name 'small_thumbnail' already exists." + help: + type: string + example: For support kindly contact us at support@imagekit.io. + "401": *a1 + "403": *a2 + "429": *a3 + "/v1/named-transformations/{id}": + get: + summary: Get named transformation + tags: + - Account Management API + - Named Transformations + operationId: get-named-transformation + description: Retrieves the named transformation identified by `id`. + parameters: + - &a6 + in: path + name: id + required: true + schema: + type: string + description: > + Unique identifier of the named transformation. This is the `id` returned when the named transformation was created, or `ik_ml_thumbnail` for the account's default named transformation. + responses: + "200": + description: Successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/NamedTransformation" + example: + id: "6bZ9x2ZUx" + name: "small_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-resize" + disabled: false + isDefault: false + createdAt: "2024-01-10T09:00:00.000Z" + "401": *a1 + "403": *a2 + "404": &a8 + description: Named transformation not found. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Named transformation with id "6bZ9x2ZUx" not found.' + help: + type: string + example: For support kindly contact us at support@imagekit.io. + "429": *a3 + patch: + summary: Update named transformation + tags: + - Account Management API + - Named Transformations + operationId: update-named-transformation + description: | + Updates the named transformation identified by `id` and returns the updated object. Only the fields present in the request body are updated; omitted fields are left unchanged. + + **Note:** The account's default named transformation (`ik_ml_thumbnail`) cannot be edited. This API returns a `400` error if attempted. + parameters: + - *a6 + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateNamedTransformation" + example: + transformation: "tr:w-200,h-200,fo-center,cm-resize" + responses: + "200": + description: Named transformation updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/NamedTransformation" + example: + id: "6bZ9x2ZUx" + name: "small_thumbnail" + transformation: "tr:w-200,h-200,fo-center,cm-resize" + disabled: false + isDefault: false + createdAt: "2024-01-10T09:00:00.000Z" + "400": + description: Bad request. The request body failed validation, or the named transformation is read-only. + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - "`name` may contain only alphanumeric characters, '_' or '-'." + - "`transformation` must start with 'tr:'." + - The default named transformation cannot be edited. + help: + type: string + example: For support kindly contact us at support@imagekit.io. + "401": *a1 + "403": *a2 + "404": *a8 + "409": *a7 + "429": *a3 + delete: + summary: Delete named transformation + tags: + - Account Management API + - Named Transformations + operationId: delete-named-transformation + description: | + Permanently deletes the named transformation identified by `id` and returns the deleted object. + + **Note:** + + - The account's default named transformation (`ik_ml_thumbnail`) cannot be deleted. This API returns a `400` error if attempted. + + - If another named transformation, or your account's upload pre-transformation/post-transformation settings, reference this named transformation (via the `n-` token), the request fails with a `409` error and the response body includes a `references` array describing where it is used. Remove those references first, then retry the deletion. This is a best-effort check and cannot detect references baked into your own application code or previously generated URLs. + parameters: + - *a6 + responses: + "200": + description: Named transformation deleted successfully. Returns the deleted object. + content: + application/json: + schema: + $ref: "#/components/schemas/NamedTransformation" + example: + id: "6bZ9x2ZUx" + name: "small_thumbnail" + transformation: "tr:w-150,h-150,fo-center,cm-resize" + disabled: false + isDefault: false + createdAt: "2024-01-10T09:00:00.000Z" + "400": + description: The default named transformation cannot be deleted. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: The default named transformation cannot be deleted. + help: + type: string + example: For support kindly contact us at support@imagekit.io. + "401": *a1 + "403": *a2 + "404": *a8 + "409": + description: | + The named transformation is referenced by another named transformation, or by an upload pre-transformation/post-transformation setting, and cannot be deleted. + content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Named transformation "small_thumbnail" is referenced by other settings and cannot be deleted.' + help: + type: string + example: For support kindly contact us at support@imagekit.io. + references: + type: array + items: + $ref: "#/components/schemas/NamedTransformationReference" + example: + message: 'Named transformation "small_thumbnail" is referenced by other settings and cannot be deleted.' + help: For support kindly contact us at support@imagekit.io. + references: + - type: "namedTransformation" + id: "8xQ2z1abc" + name: "wrapper_transform" + "429": *a3 + components: schemas: @@ -6019,6 +6307,117 @@ components: type: string format: date-time description: Timestamp when the saved extension was last updated. + CreateNamedTransformation: + title: Create Named Transformation + type: object + required: + - name + - transformation + properties: + name: + type: string + minLength: 1 + maxLength: 255 + pattern: "^[0-9a-zA-Z_-]+$" + description: | + Name of the named transformation. This is the alias used to refer to the transformation string in image and video URLs, for example `tr:n-`. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). The name `ik_ml_thumbnail` is reserved for the account's default named transformation and cannot be used. + example: "small_thumbnail" + transformation: + type: string + minLength: 1 + description: | + The transformation string this name refers to. It must start with `tr:` followed by one or more transformation parameters, for example `tr:w-150,h-150,fo-center,cm-resize`. Learn more about the [transformation syntax](https://imagekit.io/docs/transformations). + example: "tr:w-150,h-150,fo-center,cm-resize" + disabled: + type: boolean + default: false + description: | + Whether this named transformation is disabled. Set to `true` to temporarily disable it without deleting it — requests using a disabled named transformation fail at delivery time. + UpdateNamedTransformation: + title: Update Named Transformation + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + pattern: "^[0-9a-zA-Z_-]+$" + description: | + Updated name of the named transformation. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). The name `ik_ml_thumbnail` is reserved and cannot be used. This field cannot be updated for the account's default named transformation. + example: "small_thumbnail_v2" + transformation: + type: string + minLength: 1 + description: | + Updated transformation string. It must start with `tr:` followed by one or more transformation parameters. This field cannot be updated for the account's default named transformation. + example: "tr:w-200,h-200,fo-center,cm-resize" + disabled: + type: boolean + description: Whether this named transformation is disabled. + NamedTransformation: + title: Named Transformation + description: | + A named transformation is an alias for an actual transformation string, allowing you to apply and later update complex transformations without changing your image or video URLs. Learn more about [named transformations](https://imagekit.io/docs/transformations#named-transformations). + type: object + properties: + id: + type: string + description: | + Unique identifier of the named transformation. This is generated by ImageKit when you create a new named transformation, except for the account's default named transformation, whose `id` is always `ik_ml_thumbnail`. + example: "6bZ9x2ZUx" + name: + type: string + description: Name of the named transformation, used as `tr:n-` in image and video URLs. + example: "small_thumbnail" + transformation: + type: string + description: The transformation string this name refers to. + example: "tr:w-150,h-150,fo-center,cm-resize" + disabled: + type: boolean + description: Whether this named transformation is currently disabled. + example: false + isDefault: + type: boolean + readOnly: true + description: | + Whether this is the account's default named transformation (`ik_ml_thumbnail`), used internally to generate media library thumbnails. The default named transformation cannot be edited or deleted. + example: false + createdAt: + type: string + format: date-time + description: Timestamp when the named transformation was created. + example: "2024-01-10T09:00:00.000Z" + NamedTransformationReference: + title: Named Transformation Reference + description: | + Describes a location where a named transformation is referenced, which prevents it from being deleted. This is a best-effort check based on scanning other named transformations' transformation strings, and your account's upload pre-transformation and post-transformation settings, for a `n-` token. It cannot detect references baked into your own application code or previously generated URLs. + type: object + properties: + type: + type: string + enum: + - namedTransformation + - uploadPreTransformation + - uploadPostTransformation + description: | + The kind of setting referencing this named transformation — another named transformation (`namedTransformation`), your account's upload pre-transformation setting (`uploadPreTransformation`), or one of your account's upload post-transformation settings (`uploadPostTransformation`). + example: "namedTransformation" + id: + type: string + description: | + `id` of the referencing named transformation. Only present when `type` is `namedTransformation`. + example: "8xQ2z1abc" + name: + type: string + description: | + `name` of the referencing named transformation. Only present when `type` is `namedTransformation`. + example: "wrapper_transform" + index: + type: integer + description: | + Index of the referencing entry in the account's upload post-transformation settings array. Only present when `type` is `uploadPostTransformation`. + example: 0 Extensions: title: Extensions Array type: array diff --git a/stainless-config/main.yaml b/stainless-config/main.yaml index 787c8a8..51ed322 100644 --- a/stainless-config/main.yaml +++ b/stainless-config/main.yaml @@ -96,6 +96,8 @@ resources: openapi_uri: '#/components/schemas/SavedExtension' ExtensionConfig: openapi_uri: '#/components/schemas/ExtensionConfig' + NamedTransformation: + openapi_uri: '#/components/schemas/NamedTransformation' SrcOptions: openapi_uri: '#/components/schemas/SrcOptions' GetImageAttributesOptions: @@ -205,6 +207,14 @@ resources: update: patch /v1/saved-extensions/{id} delete: delete /v1/saved-extensions/{id} + namedTransformations: + methods: + list: get /v1/named-transformations + create: post /v1/named-transformations + get: get /v1/named-transformations/{id} + update: patch /v1/named-transformations/{id} + delete: delete /v1/named-transformations/{id} + assets: methods: list: get /v1/files From 348999a454ad7cc763809ad9c9d47ae390537a20 Mon Sep 17 00:00:00 2001 From: Harshit Budhraja Date: Wed, 29 Jul 2026 12:54:51 +0530 Subject: [PATCH 2/3] fix: addressed review comments to abstract ik_ml_thumbnail from the public API view --- openapi/v1.0.0.yaml | 52 ++++++++------------------------------------- 1 file changed, 9 insertions(+), 43 deletions(-) diff --git a/openapi/v1.0.0.yaml b/openapi/v1.0.0.yaml index 4572fdc..04c4413 100644 --- a/openapi/v1.0.0.yaml +++ b/openapi/v1.0.0.yaml @@ -4111,18 +4111,7 @@ paths: - Named Transformations operationId: list-named-transformations description: | - Returns an array of all named transformations configured for your account, including the account's default named transformation (`ik_ml_thumbnail`), which is used internally to generate media library thumbnails. - - **Note:** Use the `includeDefault` query parameter to exclude the account's default named transformation (`ik_ml_thumbnail`) from the response. - parameters: - - in: query - name: includeDefault - required: false - description: | - Set to `false` to exclude the account's default named transformation (`ik_ml_thumbnail`) from the response. - schema: - type: boolean - default: true + Returns an array of all named transformations configured for your account. responses: "200": description: Array of named transformation objects. @@ -4133,17 +4122,10 @@ paths: items: $ref: "#/components/schemas/NamedTransformation" example: - - id: "ik_ml_thumbnail" - name: "ik_ml_thumbnail" - transformation: "tr:w-150,h-150,fo-center,cm-pad_resize" - disabled: false - isDefault: true - createdAt: "2019-10-03T15:22:28.297Z" - id: "6bZ9x2ZUx" name: "small_thumbnail" transformation: "tr:w-150,h-150,fo-center,cm-resize" disabled: false - isDefault: false createdAt: "2024-01-10T09:00:00.000Z" "401": *a1 "403": *a2 @@ -4182,7 +4164,6 @@ paths: name: "small_thumbnail" transformation: "tr:w-150,h-150,fo-center,cm-resize" disabled: false - isDefault: false createdAt: "2024-01-10T09:00:00.000Z" "400": description: Bad request. The request body failed validation. @@ -4195,7 +4176,6 @@ paths: type: string examples: - "`name` is required and may contain only alphanumeric characters, '_' or '-'." - - "\"ik_ml_thumbnail\" is reserved for the default named transformation and cannot be used." - "`transformation` is required and must start with 'tr:'." help: type: string @@ -4232,7 +4212,7 @@ paths: schema: type: string description: > - Unique identifier of the named transformation. This is the `id` returned when the named transformation was created, or `ik_ml_thumbnail` for the account's default named transformation. + Unique identifier of the named transformation. This is the `id` returned when the named transformation was created. responses: "200": description: Successful response. @@ -4245,7 +4225,6 @@ paths: name: "small_thumbnail" transformation: "tr:w-150,h-150,fo-center,cm-resize" disabled: false - isDefault: false createdAt: "2024-01-10T09:00:00.000Z" "401": *a1 "403": *a2 @@ -4271,8 +4250,6 @@ paths: operationId: update-named-transformation description: | Updates the named transformation identified by `id` and returns the updated object. Only the fields present in the request body are updated; omitted fields are left unchanged. - - **Note:** The account's default named transformation (`ik_ml_thumbnail`) cannot be edited. This API returns a `400` error if attempted. parameters: - *a6 requestBody: @@ -4295,10 +4272,9 @@ paths: name: "small_thumbnail" transformation: "tr:w-200,h-200,fo-center,cm-resize" disabled: false - isDefault: false createdAt: "2024-01-10T09:00:00.000Z" "400": - description: Bad request. The request body failed validation, or the named transformation is read-only. + description: Bad request. The request body failed validation. content: application/json: schema: @@ -4309,7 +4285,6 @@ paths: examples: - "`name` may contain only alphanumeric characters, '_' or '-'." - "`transformation` must start with 'tr:'." - - The default named transformation cannot be edited. help: type: string example: For support kindly contact us at support@imagekit.io. @@ -4329,8 +4304,6 @@ paths: **Note:** - - The account's default named transformation (`ik_ml_thumbnail`) cannot be deleted. This API returns a `400` error if attempted. - - If another named transformation, or your account's upload pre-transformation/post-transformation settings, reference this named transformation (via the `n-` token), the request fails with a `409` error and the response body includes a `references` array describing where it is used. Remove those references first, then retry the deletion. This is a best-effort check and cannot detect references baked into your own application code or previously generated URLs. parameters: - *a6 @@ -4346,10 +4319,9 @@ paths: name: "small_thumbnail" transformation: "tr:w-150,h-150,fo-center,cm-resize" disabled: false - isDefault: false createdAt: "2024-01-10T09:00:00.000Z" "400": - description: The default named transformation cannot be deleted. + description: Bad request. content: application/json: schema: @@ -4357,7 +4329,7 @@ paths: properties: message: type: string - example: The default named transformation cannot be deleted. + example: Bad request. help: type: string example: For support kindly contact us at support@imagekit.io. @@ -6320,7 +6292,7 @@ components: maxLength: 255 pattern: "^[0-9a-zA-Z_-]+$" description: | - Name of the named transformation. This is the alias used to refer to the transformation string in image and video URLs, for example `tr:n-`. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). The name `ik_ml_thumbnail` is reserved for the account's default named transformation and cannot be used. + Name of the named transformation. This is the alias used to refer to the transformation string in image and video URLs, for example `tr:n-`. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). example: "small_thumbnail" transformation: type: string @@ -6343,13 +6315,13 @@ components: maxLength: 255 pattern: "^[0-9a-zA-Z_-]+$" description: | - Updated name of the named transformation. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). The name `ik_ml_thumbnail` is reserved and cannot be used. This field cannot be updated for the account's default named transformation. + Updated name of the named transformation. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive). example: "small_thumbnail_v2" transformation: type: string minLength: 1 description: | - Updated transformation string. It must start with `tr:` followed by one or more transformation parameters. This field cannot be updated for the account's default named transformation. + Updated transformation string. It must start with `tr:` followed by one or more transformation parameters. example: "tr:w-200,h-200,fo-center,cm-resize" disabled: type: boolean @@ -6363,7 +6335,7 @@ components: id: type: string description: | - Unique identifier of the named transformation. This is generated by ImageKit when you create a new named transformation, except for the account's default named transformation, whose `id` is always `ik_ml_thumbnail`. + Unique identifier of the named transformation. This is generated by ImageKit when you create a new named transformation. example: "6bZ9x2ZUx" name: type: string @@ -6377,12 +6349,6 @@ components: type: boolean description: Whether this named transformation is currently disabled. example: false - isDefault: - type: boolean - readOnly: true - description: | - Whether this is the account's default named transformation (`ik_ml_thumbnail`), used internally to generate media library thumbnails. The default named transformation cannot be edited or deleted. - example: false createdAt: type: string format: date-time From 21c56fbb0c11560691259906ba2efe1c9de653e9 Mon Sep 17 00:00:00 2001 From: "ImageKit.io" <45416977+imagekitio@users.noreply.github.com> Date: Wed, 5 Aug 2026 10:19:29 +0530 Subject: [PATCH 3/3] sync with sdk --- openapi/v1.0.0.yaml | 46 ++++----------------------------------------- 1 file changed, 4 insertions(+), 42 deletions(-) diff --git a/openapi/v1.0.0.yaml b/openapi/v1.0.0.yaml index 04c4413..3c1d9eb 100644 --- a/openapi/v1.0.0.yaml +++ b/openapi/v1.0.0.yaml @@ -4304,7 +4304,7 @@ paths: **Note:** - - If another named transformation, or your account's upload pre-transformation/post-transformation settings, reference this named transformation (via the `n-` token), the request fails with a `409` error and the response body includes a `references` array describing where it is used. Remove those references first, then retry the deletion. This is a best-effort check and cannot detect references baked into your own application code or previously generated URLs. + - If another named transformation, or your account's upload pre-transformation/post-transformation settings, reference this named transformation (via the `n-` token), the request fails with a `409` error whose `message` describes what it is referenced by. Remove those references first, then retry the deletion. This is a best-effort check and cannot detect references baked into your own application code or previously generated URLs. parameters: - *a6 responses: @@ -4346,21 +4346,13 @@ paths: properties: message: type: string - example: 'Named transformation "small_thumbnail" is referenced by other settings and cannot be deleted.' + example: 'Named transformation "small_thumbnail" cannot be deleted because it is referenced by named transformation "wrapper_transform".' help: type: string example: For support kindly contact us at support@imagekit.io. - references: - type: array - items: - $ref: "#/components/schemas/NamedTransformationReference" example: - message: 'Named transformation "small_thumbnail" is referenced by other settings and cannot be deleted.' + message: 'Named transformation "small_thumbnail" cannot be deleted because it is referenced by named transformation "wrapper_transform".' help: For support kindly contact us at support@imagekit.io. - references: - - type: "namedTransformation" - id: "8xQ2z1abc" - name: "wrapper_transform" "429": *a3 @@ -4539,7 +4531,7 @@ components: maxLength: 100 secretKey: description: > - Secret key for the bucket. When `useIAMRole` is `true`, send an empty string. + Secret key for the bucket. When `useIAMRole` is `true`, send an empty string. example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY type: string maxLength: 100 @@ -6354,36 +6346,6 @@ components: format: date-time description: Timestamp when the named transformation was created. example: "2024-01-10T09:00:00.000Z" - NamedTransformationReference: - title: Named Transformation Reference - description: | - Describes a location where a named transformation is referenced, which prevents it from being deleted. This is a best-effort check based on scanning other named transformations' transformation strings, and your account's upload pre-transformation and post-transformation settings, for a `n-` token. It cannot detect references baked into your own application code or previously generated URLs. - type: object - properties: - type: - type: string - enum: - - namedTransformation - - uploadPreTransformation - - uploadPostTransformation - description: | - The kind of setting referencing this named transformation — another named transformation (`namedTransformation`), your account's upload pre-transformation setting (`uploadPreTransformation`), or one of your account's upload post-transformation settings (`uploadPostTransformation`). - example: "namedTransformation" - id: - type: string - description: | - `id` of the referencing named transformation. Only present when `type` is `namedTransformation`. - example: "8xQ2z1abc" - name: - type: string - description: | - `name` of the referencing named transformation. Only present when `type` is `namedTransformation`. - example: "wrapper_transform" - index: - type: integer - description: | - Index of the referencing entry in the account's upload post-transformation settings array. Only present when `type` is `uploadPostTransformation`. - example: 0 Extensions: title: Extensions Array type: array