Skip to main content
POST https://api.craftkit.dev/v1/embed/form-submit/:sessionId/upload-image
Accepts a multipart/form-data upload with a single file field (an image), stores it under the session’s namespace, and returns the public URL — so the form submit payload can carry a URL instead of a raw file. Call this before posting the JSON form data.

​
Authorization

Embed session JWT only — never a project API key.
​
Authorization
string
required
Bearer <session_token> — a fill-mode session JWT. The request origin must be allow-listed, and :sessionId must match the token’s session. The submitForm permission is not required for upload — only fill mode.

​
Path parameters

​
sessionId
string
required
The embed session id. Must match the bearer token’s session.

​
Body

Send as multipart/form-data.
​
file
file
required
The image to upload. MIME type must start with image/. Max size 10 MB. The stored key is embed-uploads/{projectId}/{sessionId}/{uuid}.{ext}; the extension comes from the filename, falling back to a MIME-type mapping (jpg, png, gif, webp, svg) or .bin.

​
Response

200 with the public URL of the uploaded image.
​
url
string
Public URL of the uploaded image. Pass it back as the value of the matching image variable in the data of your form submit.

​
Errors

StatuscodeMeaning
400bad_requestRequest origin is not in the allowed origins list.
400invalid_multipartBody is not valid multipart/form-data.
400missing_fileNo file field in the form data.
401unauthorizedMissing/malformed header, or the session token failed verification.
403wrong_modeSession is not scope.mode = "fill".
404session_not_found:sessionId does not match the bearer token.
413file_too_largeFile exceeds the 10 MB limit.
415invalid_typeThe file’s MIME type is not image/*.
cURL
curl -X POST https://api.craftkit.dev/v1/embed/form-submit/$SESSION_ID/upload-image \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -F "file=@logo.png"
200
{
  "url": "https://cdn.craftkit.dev/embed-uploads/proj_01j.../sess_01j.../9f1c....png"
}