---
title: "Initiate a custom plugin file upload"
method: POST
path: "/organization/{organization_id}/kafka-connect/custom-plugin-files"
tags: ["Kafka_Connect_Custom_Plugins"]
---

# Initiate a custom plugin file upload

`POST /organization/{organization_id}/kafka-connect/custom-plugin-files`

Creates an organization\_custom\_plugin\_files record and returns a presigned S3 PUT URL the client must use to upload the JAR directly. Poll GET to check file\_status until it reaches READY or FAILED.

## Path parameters

- `organization_id` string, required

## Request body

- KafkaConnectCustomPluginFileCreateRequestBody — KafkaConnectCustomPluginFileCreateRequestBody
  - `content_type` 'application/java-archive' | 'application/zip' — MIME type of the plugin file being uploaded. Use 'application/java-archive' for a single JAR file or 'application/zip' for a ZIP plugin bundle. Defaults to 'application/java-archive' when omitted.
  - `file_description` string — Optional human-readable change notes specific to this plugin version.
  - `plugin_description` string — Optional human-readable description of the plugin (applies to all versions).
  - `plugin_name` string, required — User-provided name identifying this custom plugin (e.g. 'my-custom-connectors').
  - `plugin_version` string, required — User-provided version string for this plugin upload. Must be a valid PEP 440 version (e.g. '2.7.14', '1.0.0a1', '2.7.14.dev0').
  - `service_type` 'kafka_connect', required — The Aiven service type this plugin is intended for.

## Response `200`

Response

- KafkaConnectCustomPluginFileCreateResponse — KafkaConnectCustomPluginFileCreateResponse
  - `created_at` string, required — Creation timestamp in ISO 8601 format, always in UTC.
  - `created_by` string, required — Email address of the user who created this entity.
  - `file_description` string — Optional human-readable change notes specific to this plugin version.
  - `file_sha256` string — SHA-256 hash of the uploaded file, populated after successful verification.
  - `file_size` integer — Size of the uploaded file in bytes, populated after successful verification.
  - `file_status` 'INITIAL' | 'READY' | 'FAILED', required — Verification status of the uploaded JAR. INITIAL: upload pending or in progress. READY: verified and plugin classes discovered. FAILED: verification failed.
  - `plugin_file_id` string, required — Unique identifier for this custom plugin file upload.
  - `plugin_id` string, required — Unique identifier for the plugin identity record (shared across all versions).
  - `plugin_name` string, required — User-provided name identifying this custom plugin.
  - `plugin_version` string, required — User-provided version string for this plugin upload.
  - `updated_at` string, required — Last update timestamp in ISO 8601 format, always in UTC.
  - `updated_by` string — Email address of the user who last updated this entity.
  - `upload_info` object, required — Information required to upload the JAR to S3.
    - `content_type` 'application/java-archive' | 'application/zip', required — The Content-Type header value the client must set when issuing the S3 PUT request.
    - `max_file_size_bytes` integer, required — Maximum allowed file size in bytes. Files exceeding this limit will be rejected.
    - `upload_expiry_seconds` integer, required — Number of seconds the presigned URL remains valid.
    - `url` string — Presigned S3 URL to upload the JAR directly. Becomes null once file_status transitions to READY or FAILED.
  - `verify_error_code` integer — Machine-readable error code when file_status is FAILED.
  - `verify_error_message` string — Human-readable error message when file_status is FAILED.

## Other responses

- `400` — Invalid request parameters
- `409` — Request conflict

## Changes

- **2026-09-17** `2c34e77db4df` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/aiven/apis/aiven-api-documentation/changes/organization/:organization_id/kafka-connect/custom-plugin-files/post.md)

---

[API](https://skmtc.dev/aiven/apis/aiven-api-documentation.md) · [All operations](https://skmtc.dev/aiven/apis/aiven-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/aiven/apis/aiven-api-documentation/revisions/90f50802482d?raw)