Upload a form file
/form-filesUploads one file and returns it with 201 and a Location. Send multipart/form-data with the file in file; a JSON body is 422. Your organisation owns the file from the start, and GET /form-files lists it. There is no size or type limit of its own, only the server's PHP limits: over post_max_size (20 MB by default) is 413, and over upload_max_filesize is 422 on file. dry_run in any form is 422. Sends no webhook. DELETE /form-files/{id} undoes it.
Query parameters
Not supported. Sending dry_run in any form, even false, is 422 on this field.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
multipart/form-data, required
The file to upload.
Responses
{
"data": {
"id": "1a2b3c4d-5e6f-4071-8293-a4b5c6d7e8f9",
"name": "passport.pdf",
"size": 248173,
"created_at": "2026-06-15T10:30:00Z",
"updated_at": "2026-06-15T10:30:00Z"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request body is over the server's size limit (error.code = payload_too_large). Nothing was read or stored.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/form-files\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"