Backend Management

Download Page (.md)

The Backend Management API lets you list, inspect, test, update credentials, and disconnect storage backends connected to your workspace. Use these endpoints to audit existing connections, verify connectivity, rotate credentials without reconfiguring identity, or remove unused backends.

List all backends

Retrieve every backend currently connected to the workspace, including its type, connection state, and active mount paths.

`GET /api/v1/backends`

This endpoint takes no parameters.

curl -X GET "https://api.hoody.com/api/v1/backends" \
  -H "Authorization: Bearer YOUR_TOKEN"

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

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

Get backend details

Fetch detailed information about a specific backend, including its connection state and most recent usage timestamp.

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique backend identifier (16-character hex string)

curl -X GET "https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer YOUR_TOKEN"

const backend = await client.files.backends.getDetails({
  id: "a1b2c3d4e5f67890"
});

{
  "id": "a1b2c3d4e5f67890",
  "backend_type": "ssh",
  "server": "ssh:generic",
  "user": "deploy",
  "connected": true,
  "mount_paths": ["/mnt/storage-a1b2c3d4e5f67890"],
  "created_at": "2025-01-15T10:30:00Z",
  "last_used": "2025-03-22T08:14:55Z"
}

Test backend connection

Verify that a backend is reachable and its credentials are still valid.

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique backend identifier (16-character hex string)

curl -X GET "https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890/test" \
  -H "Authorization: Bearer YOUR_TOKEN"

const result = await client.files.backends.testConnection({
  id: "a1b2c3d4e5f67890"
});

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

Update backend credentials

Rotate credentials (passwords, tokens, OAuth refresh tokens, S3 keys, passphrases) for an existing backend connection. Identity fields such as host, user, port, and type cannot be changed through this endpoint — disconnect and reconnect to change those. The backend must have no active or in-progress mounts; unmount first.

No-op rotations (sending the same value that is already stored) succeed without contacting the remote.

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

Parameters

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

Request Body

The request body is an object whose keys identify which credential to rotate. Values must be strings or null; sending null deletes the stored credential.

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, private_key.

curl -X PUT "https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new-ssh-password-9k2x",
    "passphrase": "new-key-passphrase"
  }'

const result = await client.files.backends.update({
  id: "a1b2c3d4e5f67890",
  data: {
    password: "new-ssh-password-9k2x",
    passphrase: "new-key-passphrase"
  }
});

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

{
  "success": false,
  "error": "Disallowed field: hostname. Only credential fields may be updated."
}

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

{
  "success": false,
  "error": "Backend has active mounts. Unmount all paths 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."
}

Disconnect backend

Permanently remove a backend connection. Any files previously mounted from this backend will become inaccessible until the backend is reconnected.

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique backend identifier (16-character hex string)

curl -X DELETE "https://api.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer YOUR_TOKEN"

const result = await client.files.backends.disconnect({
  id: "a1b2c3d4e5f67890"
});

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