File and Download APIs

These endpoints power file retrieval and download behavior.

Authentication Requirements (As Implemented)

Unprotected files (password_hash not set): no authentication required.
Password-protected files: request is accepted only when password hash matches via one of these mechanisms:
- X-Password header
- HTTP Basic auth password
- HTTP Bearer token value
- previously stored session password hash (if present)
If password validation fails in bot/html mode, server returns 401 with WWW-Authenticate.
Password checks are applied before temporary-upload pending pages are shown.

Endpoint	Auth Required (as implemented)
`GET /s/:file`	Public unless file has password; then one accepted password mechanism is required
`GET /d/:file`	Public unless file has password; then one accepted password mechanism is required
`GET /:file`	Public unless file has password; then one accepted password mechanism is required
`HEAD /s/:file`, `HEAD /d/:file`, `HEAD /:file`	Same auth behavior as corresponding `GET` routes
`OPTIONS /s/:path`, `OPTIONS /d/:path`, `OPTIONS /:file`	None

Request and Response Examples

`GET /s/:file`

Raw stream response for file content.

Example:

curl -L https://file.ax/s/abcde

`GET /d/:file`

Forced download response with Content-Disposition: attachment.

Example:

curl -L -OJ https://file.ax/d/abcde

`GET /:file`

Behavior depends on stored metadata:

pending page for temporary upload holds (resource_type = 3)
redirect for link resources (resource_type = 1)
direct serving for bot/skip-embedded routes
embedded preview page otherwise

Temporary Upload Hold Responses

Temporary upload holds are created by chunked upload init when reserveTemporaryHold: true is used.

While the file is still uploading:

GET /:file, GET /d/:file, or GET /s/:file returns 202 and renders the pending upload page.
JSON/bot-style access receives a 202 JSON response.
HEAD /:file, HEAD /d/:file, and HEAD /s/:file return 202.

Pending JSON response:

{
  "status": "uploading",
  "message": "This file is currently being uploaded."
}

The pending page polls once per second:

GET /:file?uploadStatus=1

Status while still uploading (202):

{
  "status": "uploading",
  "ready": false
}

Status after finalize upgrades the hold (200):

{
  "status": "available",
  "ready": true,
  "downloadUrl": "/d/abcde"
}

If “Auto download when ready” is unchecked, the pending page reloads when the file becomes available. If the user manually checks it, the page navigates to downloadUrl when ready.

Password-Protected Access Examples

Using X-Password header:

curl -H "X-Password: myfilepass" https://file.ax/abcde

Using Basic auth (username ignored, password used):

curl -u "anyuser:myfilepass" https://file.ax/abcde

Using Bearer token value as password:

curl -H "Authorization: Bearer myfilepass" https://file.ax/abcde

Unauthorized Response Example

When password is missing/wrong in bot/html mode:

Status: 401
Header: WWW-Authenticate: Basic realm="<path>"
Body:

{
  "error": "Password required / wrong",
  "guide": "curl https://anyusername:PASSWORD@file.ax/abcde",
  "guide2": "Any username will work, just use the password",
  "guide3": "You may also pass the X-Password header with the password: curl -H \"X-Password: PASSWORD\" https://file.ax/abcde"
}

CORS and Preflight

`OPTIONS /s/:path`, `OPTIONS /d/:path`, `OPTIONS /:file`

Returns permissive CORS headers for file retrieval endpoints.