# API

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

Most `/api` routes require:

```text
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`