REST API

The REST API provides JSON endpoints for file operations, user management, sharing, and server administration.

All endpoints are prefixed with /api/. Authentication is required when --admin-user or --oidc-issuer is configured.

Health Endpoints

Health check

curl http://localhost:8080/.well-known/ferro

{
  "version": "2.5.1",
  "storage": "ok"
}

Liveness probe

curl http://localhost:8080/healthz

Readiness probe

curl http://localhost:8080/readyz

{
  "status": "ok",
  "subsystems": {
    "storage": "ok",
    "metadata": "persistent"
  }
}

Server Configuration

Get capabilities

curl http://localhost:8080/api/config

{
  "version": "2.5.1",
  "auth_enabled": true,
  "search_enabled": true,
  "wasm_workers_enabled": false,
  "cedar_enabled": false,
  "metadata_persistent": true,
  "cas_enabled": true,
  "storage": "configured",
  "external_url": "http://localhost:8080",
  "wopi_configured": false
}

File Operations

Upload a file (WebDAV PUT)

curl -X PUT http://localhost:8080/documents/hello.txt \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: text/plain" \
  -d "Hello, Ferro!"

Download a file

curl http://localhost:8080/documents/hello.txt \
  -H "Authorization: Bearer TOKEN" -o hello.txt

Move a file

curl -X POST http://localhost:8080/api/files/move \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from": "/documents/hello.txt", "to": "/archive/hello.txt"}'

Copy a file

curl -X POST http://localhost:8080/api/files/copy \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from": "/documents/hello.txt", "to": "/backup/hello.txt"}'

Encrypt a file

curl -X POST http://localhost:8080/api/files/encrypt \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/documents/secret.txt", "passphrase": "my-password"}'

Decrypt a file

curl -X POST http://localhost:8080/api/files/decrypt \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/documents/secret.txt", "passphrase": "my-password"}'

User Management

Create a user

curl -X POST http://localhost:8080/api/admin/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "newuser", "password": "SecurePass123!", "role": "user"}'

List users

curl http://localhost:8080/api/admin/users \
  -H "Authorization: Bearer TOKEN"

Get current user

curl http://localhost:8080/api/users/me \
  -H "Authorization: Bearer TOKEN"

Reset a user's password

curl -X POST http://localhost:8080/api/admin/users/1/reset-password \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "NewPass456!"}'

Sharing

curl -X POST http://localhost:8080/api/shares \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/documents/report.pdf", "password": "secret123", "expires_hours": 48}'

List shares

curl http://localhost:8080/api/shares \
  -H "Authorization: Bearer TOKEN"

Delete a share

curl -X DELETE http://localhost:8080/api/shares/TOKEN \
  -H "Authorization: Bearer TOKEN"

Access a shared file

curl http://localhost:8080/s/TOKEN -o report.pdf

Tags

Add tags to a file

curl -X POST http://localhost:8080/api/tags/documents/report.pdf \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["important", "finance"]}'

Get tags for a file

curl http://localhost:8080/api/tags/documents/report.pdf \
  -H "Authorization: Bearer TOKEN"

Search by tag

curl "http://localhost:8080/api/tags/search?tag=important" \
  -H "Authorization: Bearer TOKEN"

Remove a tag

curl -X DELETE http://localhost:8080/api/tags/documents/report.pdf/important \
  -H "Authorization: Bearer TOKEN"

Batch Operations

Batch copy

curl -X POST http://localhost:8080/api/batch/copy \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"from": "/a.txt", "to": "/backup/a.txt"},
    {"from": "/b.txt", "to": "/backup/b.txt"}
  ]}'

Batch move

curl -X POST http://localhost:8080/api/batch/move \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"from": "/a.txt", "to": "/archive/a.txt"},
    {"from": "/b.txt", "to": "/archive/b.txt"}
  ]}'

Bulk delete

curl -X POST http://localhost:8080/api/bulk/delete \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/a.txt", "/b.txt", "/c.txt"]}'

Full-text search

curl "http://localhost:8080/api/search?q=report&limit=10" \
  -H "Authorization: Bearer TOKEN"

Trash

List trashed items

curl http://localhost:8080/api/trash \
  -H "Authorization: Bearer TOKEN"

Restore from trash

curl -X POST http://localhost:8080/api/trash/restore \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/documents/old-file.txt"}'

Empty trash

curl -X DELETE http://localhost:8080/api/trash/empty \
  -H "Authorization: Bearer TOKEN"

Snapshots

Create a snapshot

curl -X POST http://localhost:8080/api/snapshots \
  -H "Authorization: Bearer TOKEN"

List snapshots

curl http://localhost:8080/api/snapshots \
  -H "Authorization: Bearer TOKEN"

Restore a snapshot

curl -X POST http://localhost:8080/api/snapshots/1/restore \
  -H "Authorization: Bearer TOKEN"

Storage Stats

curl http://localhost:8080/api/storage/stats \
  -H "Authorization: Bearer TOKEN"

Audit Log

curl "http://localhost:8080/api/audit?limit=50&offset=0" \
  -H "Authorization: Bearer TOKEN"