Backend Management

Use these endpoints to list, inspect, test, update, and disconnect storage backends connected to a container’s files service. All operations share the base URL https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com.

List and Inspect

GET /api/v1/backends

Get list of all connected backends.

This endpoint takes no parameters.

cURL

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.list();

200

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

GET /api/v1/backends/{id}

Get detailed information about a specific backend.

Parameters

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

cURL

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.getDetails('a1b2c3d4e5f67890');

200

{
  "id": "a1b2c3d4e5f67890",
  "backend_type": "s3",
  "server": "s3:generic",
  "user": "user",
  "connected": true,
  "mount_paths": ["/mnt/s3-bucket"],
  "created_at": "2025-01-15T08:30:00Z",
  "last_used": "2025-01-16T11:42:07Z"
}

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

Verify that a backend connection is working.

Parameters

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

cURL

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/a1b2c3d4e5f67890/test" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.testConnection('a1b2c3d4e5f67890');

200

{
  "success": true,
  "message": "Connection to s3 backend is healthy"
}

Modify and Disconnect

PUT /api/v1/backends/{id}

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; disconnect and reconnect to change those.

Caution

The backend must have no active or in-progress mounts. Unmount first. No-op rotations (same values) succeed without contacting the remote. Some backends (for example S3 with strict IAM) may reject the credential probe even with valid credentials if root listing is disallowed; use the test connection endpoint or disconnect/reconnect in that case.

Parameters

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

Request Body

A JSON object containing the credential fields to rotate. Allowed keys: 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. Values must be strings or null (passing null deletes the field).

{
  "secret_access_key": "new-secret-value",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE"
}

cURL

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_access_key": "new-secret-value",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.update('a1b2c3d4e5f67890', {
  secret_access_key: 'new-secret-value',
  access_key_id: 'AKIAIOSFODNN7EXAMPLE'
});

200

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

400

{
  "success": false,
  "error": "Invalid request: unrecognized credential field 'foo'"
}

404

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

409

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

413

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

500

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

502

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

DELETE /api/v1/backends/{id}

Remove a backend connection.

Parameters

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

cURL

curl -X DELETE "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/a1b2c3d4e5f67890" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.disconnect('a1b2c3d4e5f67890');

200

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