iron/docs/api.md

API

Iron exposes JSON APIs under /api and tus upload transport under /files.

Most /api routes require:

Authorization: Bearer <token>

Auth

• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me

Directories

• GET /api/directories/{directory_id}/children
• POST /api/directories
• POST /api/directories/{directory_id}/rename
• POST /api/directories/{directory_id}/move

Files

• GET /api/files/{file_id}
• GET /api/files/{file_id}/download
• GET /api/files/{file_id}/preview
• GET /api/files/{file_id}/stream
• POST /api/files/{file_id}/rename
• POST /api/files/{file_id}/move
• DELETE /api/files/{file_id}
• POST /api/files/{file_id}/restore
• GET /api/files/recycle-bin

Uploads

Protocol endpoints:

• POST /files
• HEAD /files/{upload_id}
• PATCH /files/{upload_id}

Finalize endpoint:

• POST /api/uploads/{upload_id}/finalize

Backends

• GET /api/backends
• POST /api/backends
• PATCH /api/backends/{backend_id}
• POST /api/backends/{backend_id}/check
• POST /api/backends/{backend_id}/disable
• POST /api/backends/{backend_id}/enable
• DELETE /api/backends/{backend_id}

Backend type values:

• local_directory
• s3
• webdav

Backend responses include public config values plus a secret_fields list for configured credentials. Secret fields such as S3 credentials and WebDAV passwords are never echoed back in clear text. Backend updates preserve existing secret fields when they are omitted from the request config, and replace them only when a new value is provided. WebDAV configs should set root_path so Iron uses a dedicated folder tree inside the remote endpoint, which is a good fit for OpenList-managed cloud drives. Backend deletion is guarded: the backend must be disabled first, must not be the default local backend, must not still store blob replicas, and must not be referenced by placement policies.

Jobs

• GET /api/jobs
• GET /api/jobs/{job_id}
• POST /api/jobs/{job_id}/retry
• POST /api/jobs/run-pending
• POST /api/jobs/enqueue-health-checks
• POST /api/jobs/enqueue-full-reconcile

Placement Policies

• GET /api/policies/placement
• PUT /api/policies/placement/{file_class}
• GET /api/policies/placement/preview

Saving a placement policy also enqueues one full reconcile job so desired replica placement converges without a separate manual step.

Metadata Export And Recovery

• GET /api/exports/metadata
• POST /api/exports/metadata/validate
• GET /api/exports/metadata/integrity
• POST /api/exports/metadata/restore-plan
• POST /api/exports/metadata/import

Metadata import requires confirm_replace=true and a validation token from the restore-plan endpoint.

System

• GET /api/system/health
• GET /api/system/ready