Backend Management

The backend management endpoints let you list, inspect, test, rotate credentials for, and disconnect storage backends connected to your container. A backend represents a remote storage provider — such as SSH, S3, Mega, or Google Drive — that is mounted into the container’s filesystem. Use these endpoints to audit existing connections, verify connectivity before relying on a mount, and rotate secrets without rebuilding the connection from scratch.

`GET /api/v1/backends`

Get a list of all connected backends.

This endpoint takes no parameters.

curl -X GET "https://proj_abc123-cnt_xyz789-files-1.us-east-1.containers.hoody.icu/api/v1/backends"

await client.files.backends.list()

{
  "backends": [
    {
      "backend_type": "s3",
      "connected": true,
      "created_at": "2024-11-15T08:30:00Z",
      "id": "a1b2c3d4e5f67890",
      "mount_paths": ["/mnt/s3-bucket"],
      "server": "s3:generic",
      "user": "access-key-user"
    },
    {
      "backend_type": "ssh",
      "connected": true,
      "created_at": "2024-11-10T14:22:00Z",
      "id": "b2c3d4e5f67890a1",
      "mount_paths": [],
      "server": "ssh:generic",
      "user": "deploy"
    }
  ],
  "count": 2
}

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

Get detailed information about a specific backend, including its connection status, type, mount paths, and last-used timestamp.

Parameters

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

curl -X GET "https://proj_abc123-cnt_xyz789-files-1.us-east-1.containers.hoody.icu/api/v1/backends/a1b2c3d4e5f67890"

await client.files.backends.getDetails("a1b2c3d4e5f67890")

{
  "backend_type": "s3",
  "connected": true,
  "created_at": "2024-11-15T08:30:00Z",
  "id": "a1b2c3d4e5f67890",
  "last_used": "2024-12-01T17:45:12Z",
  "mount_paths": ["/mnt/s3-bucket"],
  "server": "s3:generic",
  "user": "access-key-user"
}

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

Verify that a backend connection is working without performing any I/O against the remote.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	id path parameter

curl -X GET "https://proj_abc123-cnt_xyz789-files-1.us-east-1.containers.hoody.icu/api/v1/backends/a1b2c3d4e5f67890/test"

await client.files.backends.testConnection("a1b2c3d4e5f67890")

{
  "message": "Backend connection is healthy",
  "success": true
}

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

Rotate credentials (passwords, tokens, OAuth refresh tokens, S3 keys, passphrases, and similar secrets) for an existing backend connection. Identity fields such as host, user, port, and type cannot be changed through this endpoint — disconnect and reconnect to modify those. The backend must have no active or in-progress mounts; unmount first. No-op rotations where the supplied values match the stored values succeed without contacting the remote.

Parameters

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

Request Body

The request body is a free-form credential object. Allowed 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. Values must be strings, or null to delete the field. Submit only the credential fields you want to change; omitted fields are preserved.

{
  "password": "new-strong-password-7Yk2pQ",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

curl -X PUT "https://proj_abc123-cnt_xyz789-files-1.us-east-1.containers.hoody.icu/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new-strong-password-7Yk2pQ"
  }'

await client.files.backends.update("a1b2c3d4e5f67890", {
  password: "new-strong-password-7Yk2pQ"
})

{
  "message": "Backend credentials updated successfully",
  "success": true
}

{
  "error": "Request body must contain at least one credential field",
  "success": false
}

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

{
  "error": "Backend has active mounts; unmount before rotating credentials",
  "success": false
}

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

{
  "error": "Internal server error while updating backend registry",
  "success": false
}

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

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

Remove a backend connection and tear down any associated client state. To change identity fields such as host, user, port, or type, disconnect first and then reconnect.

Parameters

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

curl -X DELETE "https://proj_abc123-cnt_xyz789-files-1.us-east-1.containers.hoody.icu/api/v1/backends/a1b2c3d4e5f67890"

await client.files.backends.disconnect("a1b2c3d4e5f67890")

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