Skip to content

feat(api): Named Transformations API #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hrhv wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat(api): Named Transformations API #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e8f394
feat(api): add named transformations endpoints for listing, creating,…
hrhv Jul 28, 2026
348999a
fix: addressed review comments to abstract ik_ml_thumbnail from the p…
hrhv Jul 29, 2026
21c56fb
sync with sdk
imagekitio Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
329 changes: 328 additions & 1 deletion openapi/v1.0.0.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4103,6 +4103,258 @@ 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.
responses:
"200":
description: Array of named transformation objects.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/NamedTransformation"
example:
- id: "6bZ9x2ZUx"
name: "small_thumbnail"
transformation: "tr:w-150,h-150,fo-center,cm-resize"
disabled: 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-<name>` 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
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 '-'."
- "`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.
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
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.
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
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` may contain only alphanumeric characters, '_' or '-'."
- "`transformation` must start with 'tr:'."
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:**

- If another named transformation, or your account's upload pre-transformation/post-transformation settings, reference this named transformation (via the `n-<name>` 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:
"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
createdAt: "2024-01-10T09:00:00.000Z"
"400":
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Bad request.
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" 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.
example:
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.
"429": *a3


components:
schemas:
Expand Down Expand Up @@ -4279,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
Expand Down Expand Up @@ -6019,6 +6271,81 @@ components:
type: string
format: date-time
description: Timestamp when the saved extension was last updated.
CreateNamedTransformation:

@imagekitio imagekitio Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest create a PR in this https://github.com/imagekit-developer/imagekit-sdk-config against main and then you can review the generated sdk on all public repos. With same branch name as your branch in imagekit-sdk-config. I have given you the access. It would happen automatically, just do not merge to main as it would change main branch of all SDKs.

If there is any issue in sdk generation, then we need to fix the spec. Let me know if you need any help.

@hrhv hrhv Jul 29, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New PR in the mentioned repository: https://github.com/imagekit-developer/imagekit-sdk-config/pull/10

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-<name>`. Can only contain alphanumeric characters, `_` and `-`, and must be unique for your account (case-insensitive).
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).
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.
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.
example: "6bZ9x2ZUx"
name:
type: string
description: Name of the named transformation, used as `tr:n-<name>` 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
createdAt:
type: string
format: date-time
description: Timestamp when the named transformation was created.
example: "2024-01-10T09:00:00.000Z"
Extensions:
title: Extensions Array
type: array
Expand Down
10 changes: 10 additions & 0 deletions stainless-config/main.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down