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