RFC: ImageKit API v2

[imagekitio]

Why this discussion

We’re kicking off a focused conversation to define ImageKit API v2—a cleaner, more consistent, and future-proof API surface with first-class developer experience and strong governance.

Goals

1. Establish a stable, well-documented OpenAPI 3.1 spec with clear semantics and examples. Submit a PR to this repo updating the OpenAPI spec.
2. Normalize resource modeling, naming, pagination, errors, and auth across all endpoints.
3. Improve DX and SDK parity (Node, Go, Python, Ruby, Java, PHP, C#) with generated clients and sensible method names.
4. Provide a predictable migration path from v1 with clear deprecations.

Non-goals

1. Adding product features unrelated to API consistency or DX.

Design principles

1. Consistency first: predictable URIs, verbs, and fields.
2. Explicit over implicit: typed enums, discriminators, and documented defaults.
3. DX matters: great examples, error messages, and SDK ergonomics.

How to contribute

1. Comment with use cases, breaking-change concerns, and SDK ergonomics.
2. Propose concrete schema snippets, endpoint shapes, or error payloads.
3. Flag any v1 pain points you want v2 to solve (naming, pagination, filters, webhooks, etc.). You can also link this discussion from existing open tickets across SDK repositories.

Tracking issues

• Listing folders does not return customMetadata imagekit-nodejs#115
• Return type of listFiles method should take into account input parameters imagekit-nodejs#114
• Paginate in list api
• Perform DAM operation using file path not just fileID. Think about encoding issues that comes with path in GET requests without bdoy.
• Avoid reserved language specific properties e.g. url in charp SDK becomes urlValue in purge API. See if we can avoid this across languages.
• Unions should have a discriminator properoty. Our update file operation (update vs publish) lacks it.
• Ensure consistent error message shape. Just message is enough. And improve message so that LLM can do better. E.g. this copy file API has reason in 404, but most APIs dont have reason field.
• Make upload API to accept tags, responsive fields etc as property array. Multi-part requesst does have a starndard way to send different kind of data structures. Investigate solution. Same goes for stringified JSON inputs. At the moment, SDK do this serialization for API. Users dont notice it while using SDK. Might require breaking change in V2, so we have to tackle rclone integration as that users V2.
• Improve usage api to include analytics data that we show in dashboard. Might consider renaming it to analytics endpoint.
• Pivot to snake case from camel case in request and response body.
• Pivot to kabab case in endpoint URI.
• Discontinue metadata APIs as all the information is already there in LIST/GET file detail APIs.
• Simplify list assets API. Remove fileType, path etc properites and let searchQuery be the single source of truth related to search intent.
• Get rid of responseFields in upload API request and always send all fields.
• In upload API response, get rid of legacy metadata in favor of embeddedMetadata that has everything.
• Make response helpful in certain APIs e.g. in copy/move the payload is empty, thought it could have been new asset object.
• Pivot to using the word asset instead of file or folder e.g. see list API.
• Rename list API to search API.
• If response status is 204, then dont even send empty object {}. Check copy file response.
• Use proper status code to indicate async nature e.g. copy folder API.
• Evaulate adding Idempotency keys in certain operations e.g. copy/move/delete/rename.
• Do we really need rename file/folder API instead of just update asset API.
• Origin update API should be PATCH instead of current PUT. It was in theory done for Terraform which never went live and created tons of problem when adding new fields.
• The webhook we take in update API for extension status, doesnt confirm to our other standard webhook shape. Drop this property from all APIs and move every webhook to standard. Let user pick event type from dashboard and receive confirmed shapes.