MyRealm Vault

Developers

Everything you can do with a file here, a script can do too: upload it, list it, share it, delete it. The API is plain HTTP and JSON.

Authentication

Create a token in Settings and send it as a bearer token on every request. A token acts as your account.

export TOKEN=pat_…

curl -H "Authorization: Bearer $TOKEN" https://vault.myrealm.online/api/v1/files

A token is shown once, when it is made. It works only on the routes on this page, and stops working if you revoke it or the account is closed. The API is meant for scripts and servers: it does not accept a browser session, and does not answer requests made by a page on another site.

Create a token

Files and links

  • GET /api/v1/files?q=&page=

    Your files, newest first, fifty to a page.

  • GET /api/v1/files/:id

    One file, its share links and its public address.

  • DELETE /api/v1/files/:id

    Deletes it. It can be restored for 7 days, from the website.

  • POST /api/v1/files/:id/links

    Creates a share link. Optional: label, password, expiresInDays, maxDownloads.

curl -H "Authorization: Bearer $TOKEN" "https://vault.myrealm.online/api/v1/files?q=report"

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"expiresInDays": 7, "maxDownloads": 10}' \
  https://vault.myrealm.online/api/v1/files/$FILE_ID/links

Uploading

A file is sent in parts of 32 MB straight to storage, not through us, so you need its SHA-256 and its size before you start. Files can be up to 2 GB on the free plan.

  1. Begin the upload with the file’s hash, size and name. You get an upload id and an address for each part - or, if you already have this exact file, its id straight away.
  2. PUT each part’s bytes to its address, and note the ETag in the answer.
  3. Tell us each part was stored, with its number and ETag.
  4. Complete the upload. We read the stored file back and check its hash; the answer is 202 until that is done, then the file’s id.

  • POST /api/v1/uploads

    Begins an upload: hash, sizeBytes, filename, contentType.

  • GET /api/v1/uploads/:id

    Where it has got to, and which parts are stored.

  • POST /api/v1/uploads/:id/parts

    More part addresses: from, count.

  • POST /api/v1/uploads/:id/record-part

    A part was stored: partNumber, etag.

  • POST /api/v1/uploads/:id/complete

    Finishes it. 202 while it is verified.

  • DELETE /api/v1/uploads/:id

    Abandons it and removes what was sent.

HASH=$(sha256sum photo.jpg | cut -d' ' -f1)
SIZE=$(stat -c%s photo.jpg)

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"hash\":\"$HASH\",\"sizeBytes\":$SIZE,\"filename\":\"photo.jpg\",\"contentType\":\"image/jpeg\"}" \
  https://vault.myrealm.online/api/v1/uploads

# for each part: PUT the bytes to its url, then tell us its ETag
curl -X PUT --data-binary @photo.jpg -D - "$PART_URL"
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"partNumber\":1,\"etag\":\"$ETAG\"}" https://vault.myrealm.online/api/v1/uploads/$UPLOAD_ID/record-part

# repeat while the answer is 202
curl -X POST -H "Authorization: Bearer $TOKEN" https://vault.myrealm.online/api/v1/uploads/$UPLOAD_ID/complete

Public image addresses

An image of up to 25 MB can be given a public address to use in a page or an app: JPEG, PNG, GIF, WebP or AVIF. Anyone with the address can load it, with no password and no count. Where this is not offered yet, these routes answer 404.

  • POST /api/v1/files/:id/publish

    Publishes the image and returns its address.

  • DELETE /api/v1/files/:id/publish

    Takes the address away.

Limits and errors

  • Up to 300 requests a minute for each token. Beyond that the answer is 429; wait and try again.
  • An error is a JSON object with a code and a message. The code is stable; the message is for people.
  • 401 means the token is missing, wrong or revoked. 404 means there is no such thing, or it is not yours.
  • Your storage quota and file size limit are the same as on the website.