Upload and delivery API

Hosts

Fotolane answers on two hosts. Each one is a separate edge network in front of the same origin in Tallinn.

Our upload and gallery components keep a session on both hosts and move to the other one when the first stops answering.

Authentication

Two equivalent ways to present a project token.

A request without a recognised token is answered with 401 and an empty body. The endpoint deliberately does not describe why a token was rejected.

Whole-file upload

The simplest form. Suitable up to roughly 64 MB per request.

POST /api/uploadFile/ HTTP/1.1
Host: img.vikmen.run
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----fl

------fl
Content-Disposition: form-data; name="file"; filename="porch-light.jpg"
Content-Type: image/jpeg

<binary>
------fl--

Chunked upload

For large originals, flaky mobile links, or anything you want to resume. Open a session, then send parts in any order.

# send part 7 of an open session
curl -X POST "https://img.vikmen.run/api/uploadFile/?auth=$SID&chunk_id=7" \
  --data-binary @part-07.bin

# poll session state (GET on the same path)
curl "https://img.vikmen.run/api/uploadFile/?auth=$SID"

Sessions stay open for 30 minutes after the last accepted part. Parts are held in edge storage and are never cached: the endpoint always answers with Cache-Control: no-store.

Part integrity

Every chunked request carries a signature of its own payload.

The signature is recomputed per request, so it differs for every part even when the same bytes are re-sent after a retry. Delivery sessions send the same header in a longer form: the address of the segment, with the signature in its _dc parameter.

Browser clients (CORS)

The endpoint answers preflight requests, so uploads can run straight from a page.

OPTIONS /api/uploadFile/ HTTP/1.1

<- 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Part-Checksum
Access-Control-Max-Age: 86400

Because a browser cannot attach an Authorization header to a form post without dropping into fetch(), browser uploads normally pass the session token as ?auth= instead. Both paths are equivalent server-side.

Delivery and transforms

Once stored, an object is addressed as /<id>/<transform>.<ext>. Parameters are joined with commas, in any order.

# 640 pixels wide, cropped to 16:9, as AVIF
curl -O "https://cdn.vikmen.run/<id>/w_640,ar_16:9,fit_cover,q_78.avif"

Unknown parameters are ignored rather than served as an error, so a typo never blanks a page.

Progressive delivery

Large originals and gallery prefetches are streamed in ordered segments instead of one long response, so a slow client can start rendering early and resume after a dropped connection.

# fetch the third segment of an open session
curl "https://cdn.vikmen.run/api/v2/streams/$SID/2"

Path-addressed segments are served from the delivery host; the query form is answered on both hosts. Either way segments carry Cache-Control: no-store: the session is per-viewer and must not be shared between them. Unlike transform URLs, a stream session expires once the object has been fully delivered.

Receiver reports

While a session is open the player tells the origin what it has already decoded, so that segments can be skipped, or sent again after a drop. A report rides on the segment request itself: in the request headers X-Data-0 … X-Data-n on the path form, in the request body on the query form. Reports are opaque and can run to several kilobytes, so a gateway in front of the player should allow at least 32 KB of request headers.

Status codes