Uploads

Store medical images, list them, mint presigned URLs, and delete them.

Uploads let you store a medical image once and refer to it afterwards by its object key, rather than re-sending the bytes. Every object is scoped to the consumer that owns the calling key. You can only ever list, read or delete your own.

Store an image

POST/api/v1/uploads

A multipart/form-data upload. Returns the object key plus a presigned URL you can use immediately.

bash

curl -X POST "https://api-diagnostics.karmat-hq.com/api/v1/uploads" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY" \
  -F "[email protected]"

json

{
  "object_key": "consumers/a1b2c3/2026/08/patient-4821-right.jpg",
  "content_type": "image/jpeg",
  "size": 842114,
  "url": "https://storage.karmat-hq.com/...&X-Amz-Expires=3600&...",
  "url_expires_in_seconds": 3600
}

object_key

string

The stable handle. Store this against your patient record. The URL is not stable, the key is.

content_type

string

Detected MIME type of the stored object.

size

integer

Bytes.

url

string

A presigned GET URL. It expires; do not persist it or embed it in a saved document.

url_expires_in_seconds

integer

Lifetime of the URL above, from the moment of issue.

Presigned URLs are bearer credentials

Anyone holding the URL can fetch the image until it expires. There is no second check. Do not log them, put them in analytics events, or send them anywhere you would not send the image itself.

List your objects

GET/api/v1/uploads

bash

curl "https://api-diagnostics.karmat-hq.com/api/v1/uploads" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY"

Mint a fresh URL

GET/api/v1/uploads/{object_key}/url

When a stored URL has expired, ask for a new one rather than re-uploading. This is the endpoint to call right before you render an image to a clinician.

bash

# The object key contains slashes, so URL-encode it.
KEY=$(python -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" \
  "consumers/a1b2c3/2026/08/patient-4821-right.jpg")

curl "https://api-diagnostics.karmat-hq.com/api/v1/uploads/$KEY/url" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY"

URL-encode the object key

Object keys contain /. Passing one raw splits the path and returns 404. Percent-encode it before interpolating.

Delete an object

DELETE/api/v1/uploads/{object_key}

bash

curl -X DELETE "https://api-diagnostics.karmat-hq.com/api/v1/uploads/$KEY" \
  -H "X-API-Key: $DIAGNOSTICS_API_KEY"

Deletion is how you honour a retention policy

Medical images are among the most sensitive data you will hold. Decide your retention window before you start storing, and schedule deletion. The API will keep an object indefinitely otherwise, and that becomes your liability rather than ours.

A workable pattern

Upload the image once; persist object_key against your own record.
Run inference. When a request carries an image, the diagnosis response returns the matching image_object_key.
Re-sign on demand at render time, never at write time. A URL stored in your database is a URL that will be expired when someone needs it.
Delete on your retention schedule, and record that you did.