# Backend Management

**Page:** api/files/managing-backends

[Download Raw Markdown](./api/files/managing-backends.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Backend Management API lets you list, inspect, test, rotate credentials on, and disconnect storage backends registered with the Hoody Files system. Use these endpoints to audit connections, verify reachability, rotate passwords and tokens without a full reconnect, and tear down backends you no longer need.


Identity fields such as host, user, port, and backend type cannot be changed with an update. To change those, disconnect the backend and reconnect it with the new values.


## List & Inspect

### `GET /api/v1/backends`

Returns all backends currently registered with the system, including their connection state and active mount paths.

This endpoint takes no parameters.



```bash
curl -X GET https://api.hoody.com/api/v1/backends \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.files.backends.list();
```


```json
{
  "backends": [
    {
      "id": "a1b2c3d4e5f67890",
      "backend_type": "ssh",
      "server": "ssh:generic",
      "user": "deploy",
      "connected": true,
      "mount_paths": ["/mnt/storage/ssh-a1b2"],
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "b2c3d4e5f6789012",
      "backend_type": "s3",
      "server": "s3:generic",
      "user": "",
      "connected": true,
      "mount_paths": [],
      "created_at": "2024-02-01T14:22:18Z"
    }
  ],
  "count": 2
}
```

| Field | Type | Description |
|-------|------|-------------|
| `backends` | array | List of backend objects |
| `backends[].id` | string | Unique backend identifier (16-char hex) |
| `backends[].backend_type` | string | Backend type (e.g., `ssh`, `s3`, `mega`, `drive`) |
| `backends[].server` | string | Server identifier (e.g., `ssh:generic`, `s3:generic`) |
| `backends[].user` | string | Username used for connection (if applicable) |
| `backends[].connected` | boolean | Whether the backend is currently connected |
| `backends[].mount_paths` | array | Filesystem paths where this backend is mounted (empty if not mounted) |
| `backends[].created_at` | string | ISO 8601 timestamp when the backend was connected |
| `count` | integer | Number of backends returned |




### `GET /api/v1/backends/{id}`

Returns detailed information about a single backend, including the last-used timestamp when available.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Backend ID (16-character hex string) |



```bash
curl -X GET https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890 \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.files.backends.getDetails("a1b2c3d4e5f67890");
```


```json
{
  "id": "a1b2c3d4e5f67890",
  "backend_type": "ssh",
  "server": "ssh:generic",
  "user": "deploy",
  "connected": true,
  "mount_paths": ["/mnt/storage/ssh-a1b2"],
  "created_at": "2024-01-15T10:30:00Z",
  "last_used": "2024-03-22T09:14:51Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique backend identifier (16-char hex) |
| `backend_type` | string | Backend type (e.g., `ssh`, `s3`, `mega`, `drive`) |
| `server` | string | Server identifier (e.g., `ssh:generic`, `s3:generic`) |
| `user` | string | Username used for connection (if applicable) |
| `connected` | boolean | Whether the backend is currently connected |
| `mount_paths` | array | Filesystem paths where this backend is mounted (empty if not mounted) |
| `created_at` | string | ISO 8601 timestamp when the backend was connected |
| `last_used` | string | Last usage timestamp (if available) |




### `GET /api/v1/backends/{id}/test`

Verifies that a backend connection is still working by probing the remote.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Backend ID (16-character hex string) |



```bash
curl -X GET https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890/test \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.files.backends.testConnection("a1b2c3d4e5f67890");
```


```json
{
  "success": true,
  "message": "Connection successful"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the connection probe succeeded |
| `message` | string | Human-readable result of the test |




## Update Credentials

### `PUT /api/v1/backends/{id}`

Rotates credentials on an existing backend. Use this to update passwords, OAuth tokens, S3 keys, passphrases, and similar secrets without tearing down the connection.


The backend must have no active, mounting, or unmounting mounts. Unmount first.



Some backends (e.g., S3 with strict IAM policies) may reject the credential probe even with valid credentials if root listing is disallowed. In that case, use `testBackendConnection` or disconnect and reconnect.


### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Backend ID (16-character hex string) |

### Request Body

The body is a JSON object containing the credential fields to update. Values must be strings, or `null` to delete a field. Common keys include `pass`, `password`, `key`, `passphrase`, `token`, `refresh_token`, `auth_token`, `bearer_token`, `session_token`, `secret`, `secret_key`, `secret_access_key`, `access_key_id`, `client_secret`, `client_id`, `service_account_credentials`, and `private_key`. No-op rotations (sending the same value already stored) succeed without contacting the remote.

```json
{
  "pass": "new-strong-password"
}
```



```bash
curl -X PUT https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pass": "new-strong-password"
  }'
```


```typescript
const result = await client.files.backends.update("a1b2c3d4e5f67890", {
  pass: "new-strong-password"
});
```


```json
{
  "success": true,
  "message": "Backend credentials updated"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the update succeeded (also `true` when no changes were detected) |
| `message` | string | Human-readable result |



```json
{
  "success": false,
  "error": "Invalid request: only credential fields are allowed"
}
```


```json
{
  "success": false,
  "error": "Backend not found"
}
```


```json
{
  "success": false,
  "error": "Backend has active mounts; unmount first"
}
```


```json
{
  "success": false,
  "error": "Request body exceeds 16 KB limit"
}
```


```json
{
  "success": false,
  "error": "Internal server error"
}
```


```json
{
  "success": false,
  "error": "Credential validation failed against the remote backend"
}
```



## Disconnect

### `DELETE /api/v1/backends/{id}`

Removes a backend connection from the registry. After this call, the backend will no longer appear in `listBackends` and its stored credentials are deleted.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Backend ID (16-character hex string) |



```bash
curl -X DELETE https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890 \
  -H "Authorization: Bearer <token>"
```


```typescript
const result = await client.files.backends.disconnect("a1b2c3d4e5f67890");
```


```json
{
  "success": true,
  "message": "Backend disconnected"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Whether the disconnect succeeded |
| `message` | string | Human-readable result |