Share pages: send a file with a preview and a download button

homeaboutvideotry it nowpricingdocs

Send anyone a link to a page with a preview of the file and a download button. The page follows the file's read access, so a private file stays private.

What the page shows

A share page lives at

https://fileboy.io/f/FILE_ID

. It has the file's name, type, size and upload date, a Download button that saves it under its name, and a Copy link button. The preview depends on the type:

Images (JPEG, PNG, WebP, BMP, TIFF): resized copies at up to 640, 1280, 1920 and 2560 pixels wide, as WebP where the browser takes it, so a phone never downloads the full original. Click to open the original.
SVG, GIF and other images: shown as they are.
PDFs: the browser's own viewer, with pages, zoom, search and print.
Video and audio files: the browser's player. Videos uploaded as videos have their own watch page with adaptive streaming instead.
Text, CSV and JSON: the start of the file (the first 256 KB) as numbered lines, a table or formatted JSON.
Anything else: a card with the file's icon, name, type and size.

Programs, scripts, archives, HTML and SVG files get a short note asking people to only open them from someone they trust. HTML is never rendered on the page.

Turn it on

A file has no share page until you turn it on. In the dashboard, open the file and use the switch on its Share & embed tab, which also has the link to copy. From code it is the

sharePage

field of

PATCH /files/FILE_ID

, which needs the private key:

// needs the private key
await fileboy.updateFileData(id, { sharePage: true })

const link = fileboy.buildSharePageUrl(id)
// https://fileboy.io/f/2a860257-ecf9-424a-846e-00ab68e2fd58

// turn it off: the link stops working at once
await fileboy.updateFileData(id, { sharePage: false })

# needs the private key
fileboy.update_file(id, share_page: true)

link = fileboy.build_share_page_url(id)
# => "https://fileboy.io/f/2a860257-ecf9-424a-846e-00ab68e2fd58"

# turn it off: the link stops working at once
fileboy.update_file(id, share_page: false)

# needs the private key
client.update_file(file_id, share_page=True)

link = client.build_share_page_url(file_id)
# "https://fileboy.io/f/2a860257-ecf9-424a-846e-00ab68e2fd58"

# turn it off: the link stops working at once
client.update_file(file_id, share_page=False)

// needs the private key
$fileboy->updateFile($id, ['sharePage' => true]);

$link = $fileboy->buildSharePageUrl($id);
// https://fileboy.io/f/2a860257-ecf9-424a-846e-00ab68e2fd58

// turn it off: the link stops working at once
$fileboy->updateFile($id, ['sharePage' => false]);

curl -X PATCH https://api.fileboy.io/files/$ID \
  -H "Authorization: token YOUR_SIGNED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sharePage": true}'

# the page's data, as the page itself reads it
curl https://api.fileboy.io/files/$ID/share

Turning it off stops the page at once, for everyone, including signed links you have already sent. It never changes the file's own URLs. Image copies Fileboy makes and the files inside a video never have a share page.

Who can open it

The page asks for the file with the same rules as every other read, described in Signed URLs:

A public file in a public app: anyone with the link can open the page. This shows nothing new: anyone with the file's id could already read it.
A file set to Signed URLs only, or any file in an app that requires signed URLs: the page only opens through a signed share link, below. Anyone else sees “This file is private”, with nothing about the file, not even whether its page is on.

A share page does not make a public file private. If the file is public, its own URL keeps working for anyone who has it. Set it to Signed URLs only when the share link should be the only way in.

Private files

Sign the page URL on your server, exactly like any other read. The page passes the signature to Fileboy, which hands it a preview and a download signed with the same expiry and address range. When the link expires, the page, the preview and the download all stop working.

// on your server, for a file that needs a signed URL. The page's preview and
// download are signed for the same week, and stop working with the link.
const link = fileboy.signSharePageUrl(id, { expiresIn: 7 * 24 * 3600 })
// https://fileboy.io/f/2a86...?fb_exp=1800000000&fb_sig=...

# on your server, for a file that needs a signed URL
link = fileboy.sign_share_page_url(id, expires_in: 7 * 24 * 3600)
# => "https://fileboy.io/f/2a86...?fb_exp=1800000000&fb_sig=..."

# on your server, for a file that needs a signed URL
link = client.sign_share_page_url(file_id, expires_in=7 * 24 * 3600)
# "https://fileboy.io/f/2a86...?fb_exp=1800000000&fb_sig=..."

// on your server, for a file that needs a signed URL
$link = $fileboy->signSharePageUrl($id, expiresIn: 7 * 24 * 3600);
// https://fileboy.io/f/2a86...?fb_exp=1800000000&fb_sig=...

# The same signature as any other read, with scope=share and the file id
EXP=$(( $(date +%s) + 7 * 24 * 3600 ))
CANON=$(printf 'FBS1\nscope=share\nid=%s\ntransform=\nfilename=\nexp=%s\nip=' "$ID" "$EXP")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
echo "https://fileboy.io/f/$ID?fb_exp=$EXP&fb_sig=$SIG"

A share link only opens the page. A signature made for the file itself (

/files/get/FILE_ID

) does not open the page, and a share link's signature does not read the file directly. The share page also has to be on, so turning it off revokes every share link of that file. Signing with

ip

limits the page, the preview and the download to that address or range.

In the dashboard, Preview the page opens it with a link signed for the next few hours, so you can see what people will get.

Link previews

Pasted into Slack, Teams, iMessage, WhatsApp, X, LinkedIn or Discord, the link unfurls with the file's name and a line like

PDF · 2.4 MB. Shared with Fileboy.

Images also get a thumbnail (a JPEG at most 1200 pixels on its longest side), video files an

og:video

tag and audio files an

og:audio

tag. A signed link previews only what it opens, and a page that is off or private previews as “This file isn't available”.

Search engines

Share pages are always sent with

noindex, nofollow

, as a header and a meta tag, so search engines are asked not to list them. That keeps them out of results, but it is not access control: anyone with the link can still open a public file's page.

Build your own page

The page reads

GET https://api.fileboy.io/files/FILE_ID/share

, which you can call too. It answers with the name, type, size and dimensions,

access

(

public

signed

expiresAt

, and the URLs to show:

view

download

images

for

srcset

and a

thumbnail

. It follows the same rules as the page: add a share link's

fb_exp

fb_sig

and

fb_ip

for a private file. See the API reference.

```
404 share_page_not_found
```
: no such file, or its page is off.
```
401 signature_required
```
: the file is private and the link isn't signed.

403 signature_expired

signature_invalid

ip_not_allowed

: as for any signed URL.

Answers are kept by the browser for at most a minute, and never by a shared cache, so turning a page off reaches everyone within a minute.

What it doesn't do yet

Passwords, download limits and view counts on the page.
Your own logo or colours on the page, or your own domain.
One page for several files.
Turning pages on for every new upload. Turn them on per file, or with
```
PATCH /files/FILE_ID
```
after the upload.

What the page showsTurn it onWho can open itPrivate filesLink previewsSearch enginesBuild your own pageWhat it doesn't do yet

Getting Started

Uploads

Delivery

Video

Libraries

API Reference

Share pages