API Documentation

File and Download APIs

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.
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:

  • redirect for link resources (resource_type = 1)
  • direct serving for bot/skip-embedded routes
  • embedded preview page otherwise

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.