Plain Endpoints (Scripts)

These endpoints are designed for shell scripts and CLI automation.

All endpoints that validate username + password in request body are documented on this page.

Why Use Plain Endpoints

No browser session dependency.
Password-based login per request.
Plain-text oriented responses for bash/curl usage.
Chunked flow is resumable for unstable networks.

Authentication Model (As Implemented)

Plain credential endpoints validate username + password in body.
uploadChunkPlain and chunkedUploadStatusPlain have no explicit auth middleware and rely on a valid upload id.
No browser connect.sid session is required.
getMe returns secondary metadata (secondaryLabel, secondaryFolderScopeId, secondaryCanListFiles, secondaryCanEditFiles, secondaryIsApiKey) when authenticated with a secondary credential.

Strong Security Recommendation

It is highly recommended to use dedicated secondary passwords for scripts.

Do not reuse your primary password in automation.
Create separate secondary passwords per script/host.
Scope secondary passwords to the smallest required folder subtree.
Rotate and revoke script passwords regularly.

Endpoint List

Method	Path	Auth Required (as implemented)	Purpose
POST	`/api/getMe`	Handler validates body `username` + `password`	Validate credentials and return auth mode (`primary`/`secondary`) plus secondary permission metadata
POST	`/api/cliCheckCredentials`	Handler validates body `username` + `password`	Quick credential validation (`VALID`/`INVALID`/`MISSING`)
POST	`/api/initChunkedUploadPlain`	Handler validates body `username` + `password`	Start resumable chunked upload session
POST	`/api/uploadChunkPlain`	No explicit auth middleware; valid upload `id` required	Upload one chunk
GET	`/api/chunkedUploadStatusPlain`	No explicit auth middleware; valid upload `id` required	Poll upload state
POST	`/api/finishChunkedUploadPlain`	Handler validates body `username` + `password`	Finalize upload and return links
POST	`/api/basicHTMLUpload`	Handler validates body `username` + `password`	Single-request multipart upload
POST	`/api/secondaryPasswords/createFromPrimary`	Handler validates body `username` + `password` and requires primary password	Create scoped secondary password in automation flow (`folderIdScope`, `canListFiles`, `canEditFiles`)

Request and Response Examples

`POST /api/getMe`

Request body (application/json or urlencoded):

{
  "username": "alice",
  "password": "my-script-password"
}

Success response (200):

{
  "ok": true,
  "username": "alice",
  "mode": "secondary",
  "secondaryLabel": "ci-runner",
  "secondaryFolderScopeId": 123,
  "secondaryCanListFiles": true,
  "secondaryCanEditFiles": false,
  "secondaryIsApiKey": false
}

Failure responses:

400: { "error": "Missing username or password" }
401: { "error": "Invalid credentials" }

`POST /api/cliCheckCredentials`

Request body (urlencoded):

username=alice&password=my-script-password

Response body (plain text):

VALID (200)
INVALID (401)
MISSING (400)

`POST /api/initChunkedUploadPlain`

Request body (urlencoded):

username=alice&password=my-script-password&filename=video.mp4&size=104857600&folderId=123

Success response (200, plain text):

3fa1c7409df3a2d4bbf7d33d5e6f7c18

Failure responses:

400: ERR Missing fields or ERR Invalid file size
401: ERR Invalid credentials
413: ERR Storage limit exceeded

`POST /api/uploadChunkPlain`

Request format:

Query: id=<upload-id>&chunk=<number>
Multipart field: file

Example:

curl -X POST \
  -F "file=@chunk-1.bin" \
  "https://file.ax/api/uploadChunkPlain?id=3fa1c7409df3a2d4bbf7d33d5e6f7c18&chunk=1"

Success response (200, plain text):

OK

Failure responses:

400: ERR Missing id or ERR Not found

`GET /api/chunkedUploadStatusPlain`

Request query:

id=<upload-id>

Responses (plain text):

PENDING

PROCESSING

COMPLETED
Link: https://file.ax/abcde
Raw: https://file.ax/s/abcde
Download: https://file.ax/d/abcde

Failure responses:

400: ERR Missing id
404: ERR Not found

`POST /api/finishChunkedUploadPlain`

Request body (urlencoded):

username=alice&password=my-script-password&id=3fa1c7409df3a2d4bbf7d33d5e6f7c18&filename=video.mp4&folderId=123

Optional body fields supported by handler: forceDownload, skipEmbeddedPage.

Success response (200, plain text):

Link: https://file.ax/abcde
Raw: https://file.ax/s/abcde
Download: https://file.ax/d/abcde

Other responses:

202: PROCESSING Retry in 5 seconds
400: ERR Missing fields or ERR Upload not found
401: ERR Invalid credentials
413: ERR Storage limit exceeded
500: ERR Reassemble failed or ERR Finalize failed

`POST /api/basicHTMLUpload`

Request format:

Multipart fields: username, password, file
Optional multipart field: folderId

Example:

curl -X POST https://file.ax/api/basicHTMLUpload \
  -F "username=alice" \
  -F "password=my-script-password" \
  -F "folderId=123" \
  -F "file=@./report.pdf"

Success response (200, plain text):

Link: https://file.ax/abcde.pdf
Raw: https://file.ax/s/abcde.pdf
Download: https://file.ax/d/abcde.pdf

Failure responses:

401: { "error": "Invalid credentials" }
400: { "error": "No file uploaded" }
413: { "error": "Storage limit exceeded", "details": "..." }

Folder Scope Notes for Script Credentials

If a secondary password has secondaryFolderScopeId set, folderId must be inside that subtree.
For scoped secondary passwords, omitted folderId defaults to the scope root.
Outside-scope folder requests return 403 with a scope-related error.
Secondary credential permissions are exposed by getMe:
- secondaryCanListFiles controls file-list UI/API access.
- secondaryCanEditFiles controls edit/move/replace operations.

Recommended Resumable Flow

Validate credentials with /api/cliCheckCredentials.
Initialize upload with /api/initChunkedUploadPlain.
Upload all chunks with /api/uploadChunkPlain.
Retry only failed chunks.
Finalize with /api/finishChunkedUploadPlain.
If finalize returns processing, retry finalize or poll status.