Upload

Endpoint

POST/utilities/upload?filename={name}

Only POST is accepted. Any other method returns 405 Method Not Allowed, so this endpoint cannot be exercised from a browser address bar.

Authentication

Send the upload key in either X-Upload-Key or Authorization. A missing or incorrect key returns 401 Unauthorized.

Either header works

-H "X-Upload-Key: YOUR_UPLOAD_KEY"
-H "Authorization: YOUR_UPLOAD_KEY"

Filename

The filename can come from either the query string or a header. If neither is present the request returns 400 Bad Request. The name is sanitized before it reaches the object store.

Source	Example
Query parameter	`?filename=image.jpg`
Request header	`X-Filename: image.jpg`

Accepted content types

The request Content-Type must be one of the following. Anything else returns 400 Bad Request.

Content-Type	Format
`image/jpeg`	JPEG
`image/jpg`	JPEG, alternate spelling
`image/png`	PNG
`image/gif`	GIF
`image/webp`	WebP
`image/svg+xml`	SVG

Size limits

Maximum body size is 10 MB.
Empty bodies are rejected.

The body is read as raw bytes, so send the file directly rather than wrapping it in a multipart form.

Usage examples

Filename in the query string

curl -X POST \
  "https://your-service.edgecompute.app/utilities/upload?filename=photo.jpg" \
  -H "X-Upload-Key: YOUR_UPLOAD_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Filename in a header

curl -X POST \
  "https://your-service.edgecompute.app/utilities/upload" \
  -H "X-Upload-Key: YOUR_UPLOAD_KEY" \
  -H "X-Filename: diagram.png" \
  -H "Content-Type: image/png" \
  --data-binary @diagram.png

Success response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "File uploaded successfully",
  "filename": "photo.jpg",
  "path": "/photo.jpg",
  "url": "https://your-object-store.example/photo.jpg",
  "size": 248391,
  "type": "image/jpeg"
}

Error responses

Status	Cause
`405`	The request used a method other than `POST`.
`401`	The upload key was missing or did not match.
`400`	No filename was supplied in the query string or headers.
`400`	The content type is not one of the accepted image types.
`400`	The body was empty or exceeded 10 MB.

Notes

Uploads are written to an object store backend. If the object store returns a non-OK status, the upload fails and the error surfaces in the response rather than being silently discarded.

Checks run in order: method, authentication, filename, content type, then body size. The first failure ends the request.
The declared Content-Type is what gets validated, not the file's actual contents.
Filenames are sanitized, so the stored name may differ from what you sent.