Backend Management

Download Page (.md)

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.

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.

curl -X GET https://api.hoody.com/api/v1/backends \
  -H "Authorization: Bearer &lt;token&gt;"

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

{
  "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)

curl -X GET https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890 \
  -H "Authorization: Bearer &lt;token&gt;"

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

{
  "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)

curl -X GET https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890/test \
  -H "Authorization: Bearer &lt;token&gt;"

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

{
  "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.

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.

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

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

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

{
  "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

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

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

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

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

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

{
  "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)

curl -X DELETE https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890 \
  -H "Authorization: Bearer &lt;token&gt;"

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

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

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