Files over the Gateway

Your workspace stores files, and your app needs to put them there and get them back. The gateway exposes four operations for that, under one path:

https://gateway.praxsuite.com/{workspaceId}/files

They authenticate like everything else on the gateway: an API key, or an end user's JWT.

The four operations

Upload returns the blob id, and that id is the whole point: it is what you put in a File-type column when you write a row.

{
  "refs": { "Documents": "…" },
  "mutation": {
    "type": "insert",
    "table": "Documents",
    "values": [{ "Title": "Contract", "Attachment": "<blob-id>" }]
  }
}

A file does not need to belong to a row to exist. Upload first, attach later, or never — an orphaned blob is a perfectly valid thing while a user is still filling in a form.

Two things the gateway refuses

Files that belong to another workspace. Every operation resolves the blob within the workspace in the route, so a valid id from somewhere else answers 404, not 403. There is no cross-workspace file access to misconfigure.

Raw storage URLs. The backend proxies all content. Your callers never receive an address that points at the underlying storage, which means access can be revoked and cannot be shared by accident.

Uploads are also checked against your plan's size limit and an allowed-extension list, and both rejections name the actual limit rather than failing vaguely.

How file URLs come back in query results

When a query returns a File or Image column, what you get depends on the calling credential's FileUrlMode:

Proxy keeps every file access behind the same permission check as the row that referenced it. That is the safe default, and it is what you want for anything private.

SasUrl trades that for URLs a browser can load with no credentials — necessary for a public gallery, and exactly wrong for a contract or an ID scan, because anyone holding the URL can open it until it expires.

FileSasExpiryMinutes defaults to 60, with a floor of 5 minutes and a ceiling of 7 days. Keep it short. Once a pre-signed URL leaves your page, its expiry is the only thing still limiting it.

This is set per credential, so a public read-only key can serve images directly while your backend key keeps everything proxied.

Choosing

Would you mind if this URL were forwarded to somebody who is not signed in? If yes, stay on Proxy.

Product photos, avatars and public marketing assets are fine on SasUrl. Anything a person uploaded about themselves is not.

Next

• Credentials and Principals — where FileUrlMode is configured.

• Mutations — writing a blob id into a row.