Downloads and public delivery

BigFS can stream an object to an authorized caller, issue a short-lived one-time download grant, or resolve a public object route.

Routes

Route	Authorization	Required input	Result
ANY /v1/download/issue	Consumer token and bucket membership	id, or key	JSON grant for a one-time download.
ANY /v1/download/link	No token	id, key	Binary file stream; consumes the grant.
ANY /v1/download/pull	Consumer token and bucket membership	id, or key	Binary file stream.
ANY /v1/download/redir	Consumer token and bucket membership	id, or key	JSON object pointer data.
ANY /v1/public/redir/<bucket>/<name>	No token	Route path, or bucket and name	HTTP redirect to the resolved object pointer.

Select an object

The download routes select an object using one of these forms:

Field set	Behavior
id	Asset UUID. The service derives its bucket, key, and version.
key	Key UUID. Optionally send version; a non-positive or omitted value selects the current resolved version.

When using key, bucket is not used to select the target. The selected bucket must be accessible to the caller for issue, pull, and redir.

Issue and consume a one-time download grant

/v1/download/issue creates a grant with a fixed 120-second lifetime. The success response exposes a ready-to-use grant.url; it contains both grant credentials and should be treated as a secret. The grant can be consumed once through /v1/download/link without an authorization header.

curl -sS https://api.bigfs.m7.org/v1/download/issue \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"id":"ASSET_UUID"}'

{
  "status": 1,
  "data": {
    "grant": {
      "id": "DOWNLOAD_GRANT_UUID",
      "key": "DOWNLOAD_GRANT_KEY",
      "expires_in": 120,
      "issued_at": "2026-08-19T00:00:00+00:00",
      "expires_at": "2026-08-19T00:02:00+00:00",
      "consume": true,
      "path": "/v1/download/link?id=DOWNLOAD_GRANT_UUID&key=DOWNLOAD_GRANT_KEY",
      "url": "https://api.bigfs.m7.org/v1/download/link?id=DOWNLOAD_GRANT_UUID&key=DOWNLOAD_GRANT_KEY"
    },
    "target": {
      "asset_id": "ASSET_UUID",
      "bucket_id": "BUCKET_UUID",
      "key_id": "KEY_UUID",
      "key_name": "reports/latest.pdf",
      "version": 1,
      "consume": true
    }
  }
}

Retrieve the file with the returned URL or with id and key as query parameters. The route responds with Content-Disposition: attachment and the file bytes. A missing, expired, invalid, or already-consumed grant fails.

Pull a file or retrieve pointer data

/v1/download/pull streams the selected file with an attachment filename. /v1/download/redir returns JSON pointer data for the selected target. Both require a consumer token and bucket membership.

curl --location --remote-name \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  'https://api.bigfs.m7.org/v1/download/pull?id=ASSET_UUID'

Public redirect

/v1/public/redir/<bucket>/<name> accepts no token. It resolves the bucket and object name from the path and sends an HTTP redirect to the first available object pointer. For example:

https://api.bigfs.m7.org/v1/public/redir/public-assets/releases/app.zip

The equivalent request fields are bucket and name. When no pointer can be resolved, the route returns HTTP 404 with a JSON error envelope.