Skip to content

API

Jump to bottom
Suryaprakash edited this page Jul 27, 2026 · 1 revision

API Reference

REST API v1 for Nexora — file workspace backend.

Base URL: https://your-domain/api/v1

Authentication

Cookie-based session: session=<jwt>; csrf_token=<token>

Mutating requests require X-CSRF-Token header.

Error Format

{
  "error": "error_code",
  "message": "Human-readable description",
  "request": "req_abc123"
}
Status Code Description
400 bad_request Invalid input
401 unauthorized Missing/invalid auth
403 forbidden Insufficient permissions
404 not_found Not found
429 rate_limited Too many requests
500 internal_error Server error

Auth Endpoints

POST /api/v1/auth/setup

Initial admin setup. Only works once.

{"username": "admin", "password": "secure", "email": "admin@example.com"}

POST /api/v1/auth/login

{"username": "admin", "password": "secure", "totp_code": "123456"}

GET /api/v1/auth/session

Current session info. Returns user object.

POST /api/v1/auth/logout, POST /api/v1/auth/password

TOTP

  • POST /auth/totp/setup → {secret, qr_code, backup_codes}
  • POST /auth/totp/verify → {code}
  • POST /auth/totp/disable → {password}

Roots

GET /api/v1/roots

[{"id": "root1", "name": "Primary", "type": "local", "permission": "write"}]

POST /api/v1/roots (admin)

{"name": "S3 Archive", "type": "s3", "config": {"bucket": "my-bucket", "region": "us-east-1"}}

Files

GET /api/v1/files

Param Type Description
root string Root ID (required)
path string Relative path
sort string name, modified, size, type
order string asc, desc
filter string all, documents, images, videos, audio, archives, folders
offset int Pagination offset
limit int Page size (max 1000)

Response:

{"items": [FileItem...], "has_more": false, "next_offset": 0}

GET /api/v1/files/stat

Single file metadata.

POST /api/v1/files/directory

Create directory: {root, path}

POST /api/v1/files/rename

{root, path, new_name}

POST /api/v1/files/move

{root, paths: [], target_root, target_path}

POST /api/v1/files/copy

Same as move.

DELETE /api/v1/files

{root, paths: []} — moves to trash.

POST /api/v1/files/upload

Multipart form: POST /api/v1/files/upload?root=root1&path=folder/

GET /api/v1/files/download

Download path(s). Supports Range header for video seeking.

GET /api/v1/files/raw

Raw file stream.

GET /api/v1/files/transcode

On-the-fly transcoding. Params: target (hls, mp4, webm, jpg, webp), width, height, quality.

Trash

GET /api/v1/trash

List trashed items.

POST /api/v1/trash/restore

{id}

DELETE /api/v1/trash

Permanent delete: {id}

Search

GET /api/v1/search

Param Type Description
q string Query
roots[] string Root IDs
filter string Type filter
offset int Pagination
limit int Page size

Versions

GET /api/v1/files/versions

List versions for a file. {root, path}

POST /api/v1/files/versions

Create version snapshot.

POST /api/v1/files/versions/{id}/restore

Restore specific version.

Playlists

GET /api/v1/playlists

POST /api/v1/playlists

{name, root, paths: []}

DELETE /api/v1/playlists/{id}

PUT /api/v1/playlists/{id} — rename

POST /api/v1/playlists/{id}/items — add items

DELETE /api/v1/playlists/{id}/items — remove items

Shares

GET /api/v1/shares

POST /api/v1/shares

{root, path, permission, password?, expires_in?}

DELETE /api/v1/shares/{token}

Public (no auth)

  • GET /api/v1/share/{token} — info
  • GET /api/v1/share/{token}/download — download
  • GET /api/v1/share/{token}/raw — raw stream
  • POST /api/v1/share/{token}/verify — password

Admin (requires admin role)

Users

  • GET /api/v1/admin/users
  • POST /api/v1/admin/users — {username, password, role}
  • PUT /api/v1/admin/users/{id}
  • DELETE /api/v1/admin/users/{id}
  • User root permissions: GET/POST/DELETE /api/v1/admin/users/{id}/roots

Audit

  • GET /api/v1/admin/audit — with pagination + filters

System

  • POST /api/v1/admin/search/reindex
  • GET /api/v1/admin/usage — storage stats

Rate Limits

Category Limit
Auth 5/min per IP
File operations 60/min per user
Search 30/min per user
Upload 10/min per user

Related Pages

Clone this wiki locally