Developer API

An HTTP API for reading and writing your own library. It follows the S3 object-storage conventions, so existing S3 clients work with minor changes. Available on Plus and Family plans.

Introduction

The API presents your library as buckets and objects, addressed per region. All calls use HTTPS and need an API token, created in Settings, Developer. Base host:

https://api.lanternbox.link/v3

Authentication

Send your token as a bearer header. Tokens are read-only or read-write and can be revoked at any time.

curl https://api.lanternbox.link/v3/albums \
  -H "Authorization: Bearer lbx_live_9f3c..."

Keep tokens on the server side. A leaked read-write token can change your library; rotate it from the dashboard if it is exposed.

Regional endpoints

Objects are kept close to you. Each region answers on its own storage host, and the API returns the correct one in every object link, so you rarely write these by hand.

Region	Location	Storage endpoint	Download server
`eu-fra-1`	Frankfurt	`s3.eu-fra-1.lanternbox.link`	`dl1.<your-domain>`
`eu-fra-2`	Frankfurt	`s3.eu-fra-2.lanternbox.link`	`dl2.<your-domain>`
`eu-hel-1`	Helsinki	`s3.eu-hel-1.lanternbox.link`	`dl3.<your-domain>`

Encryption keys are held by the key service at kms.lanternbox.link, and the account console is at console.lanternbox.link. Both need signed requests and are not part of the public data API.

Uploading

Uploads are split into parts and can be resumed. Open a session, send the parts, then commit. A part that fails can be sent again without restarting the upload.

# 1. open a session
POST /v3/uploads
{ "filename": "IMG_4021.HEIC", "size": 4823221, "sha256": "..." }
-> { "upload_id": "up_7Kp...", "part_size": 8388608 }

# 2. send each part, resumable
PUT /v3/uploads/up_7Kp.../parts/0
Content-Range: bytes 0-8388607/4823221

# 3. commit
POST /v3/uploads/up_7Kp.../commit

A session stays open while data is arriving. Connections are held for up to 24 hours, so a slow upload on mobile does not time out.

Downloading

Ask for a signed URL, then read the bytes from the nearest download server. Range requests are supported for partial downloads.

GET /v3/objects/obj_5aC.../link
-> { "url": "https://dl1.lanternbox.link/o/obj_5aC...?exp=...&sig=...",
    "expires_in": 900 }

curl -r 0-1048575 "https://dl1.lanternbox.link/o/obj_5aC...?..." -o head.bin

Command line (lbx)

The command-line tool wraps the API for backups and one-off restores.

# install
curl -fsSL https://dl1.lanternbox.link/cli/install.sh | sh

# back up a folder
lbx push ~/Pictures/2026 --album "2026"

# restore an album to disk
lbx pull --album "2026" ./restore

Release signatures

Every desktop and command-line build is served from the download servers and signed. Verify it before running:

minisign -Vm Lanternbox-4.2.0.dmg \
  -P RWQf6L...LanternboxReleaseKey

Rate limits

1,000 requests per minute per token for metadata calls. Upload and download traffic is not metered on paid plans. Over a limit, the API returns 429 with a Retry-After header. A request for a bucket you cannot access returns a standard AccessDenied document.