# API_GOLDEN.md

Dit document definieert stabiele API responses.
Velden mogen niet wijzigen zonder golden tests te updaten.

## Browse

### `GET /api/browse`
Response shape:
```json
{
  "path": "storage1",
  "directories": [],
  "files": []
}
```

## File Ops (direct)

### `POST /api/files/mkdir`
Success:
```json
{ "path": "storage1/parent/new_dir" }
```

Conflict (`already_exists`):
```json
{
  "error": {
    "code": "already_exists",
    "message": "Target path already exists",
    "details": { "path": "storage1/parent/new_dir" }
  }
}
```

Invalid name (`invalid_request`):
```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid name",
    "details": { "name": "bad/name" }
  }
}
```

### `POST /api/files/rename`
Success:
```json
{ "path": "storage1/parent/new_name.ext" }
```

Conflict (`already_exists`) + invalid name (`invalid_request`) gebruiken dezelfde error-shape als mkdir.

### `POST /api/files/delete`
Success:
```json
{ "path": "storage1/parent/file_or_empty_dir" }
```

Non-empty directory:
```json
{
  "error": {
    "code": "directory_not_empty",
    "message": "Directory is not empty",
    "details": { "path": "storage1/parent/non_empty" }
  }
}
```

## Task-based create endpoints

### `POST /api/files/copy`
### `POST /api/files/move`
Success (202):
```json
{
  "task_id": "<uuid>",
  "status": "queued"
}
```

## Tasks read endpoints

### `GET /api/tasks`
Response shape:
```json
{
  "items": [
    {
      "id": "<uuid>",
      "operation": "copy",
      "status": "running",
      "source": "storage1/a.txt",
      "destination": "storage2/a.txt",
      "created_at": "2026-03-10T10:00:00Z",
      "finished_at": null
    }
  ]
}
```

### `GET /api/tasks/{task_id}`
Response shape:
```json
{
  "id": "<uuid>",
  "operation": "move",
  "status": "running",
  "source": "storage1/a.txt",
  "destination": "storage2/a.txt",
  "done_bytes": 1024,
  "total_bytes": 4096,
  "done_items": null,
  "total_items": null,
  "current_item": "storage1/a.txt",
  "failed_item": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-03-10T10:00:00Z",
  "started_at": "2026-03-10T10:00:01Z",
  "finished_at": null
}
```

Task not found:
```json
{
  "error": {
    "code": "task_not_found",
    "message": "Task was not found",
    "details": { "task_id": "task-missing" }
  }
}
```