# Backend Connections

**Page:** api/files/backend-connections

[Download Raw Markdown](./api/files/backend-connections.md)

---

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



The Backend Connections API provides direct, on-demand access to files stored on remote systems without requiring a persistent mount. Use these endpoints to read files from FTP, S3, SSH, and Git servers, upload files via SSH/SFTP, and manage basic authentication state.

## Remote Connections

### `GET /{path}?type=ftp`

Connect to an FTP or FTPS server and retrieve a file or directory listing.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Path to the file or directory on the remote server |
| `type` | query | string | Yes | Connection type. Must be `ftp` |
| `server` | query | string | Yes | FTP server hostname |
| `user` | query | string | No | FTP username. Default: `"anonymous"` |
| `pass` | query | string | No | FTP password |
| `ftp_secure` | query | boolean | No | Use FTPS (FTP over TLS). Default: `false` |
| `ftp_passive` | query | boolean | No | Use passive mode. Default: `true` |



```bash
curl -G "https://api.hoody.com/files/var/www/index.html" \
  --data-urlencode "type=ftp" \
  --data-urlencode "server=ftp.example.com" \
  --data-urlencode "user=admin" \
  --data-urlencode "pass=secret123" \
  --data-urlencode "ftp_secure=true" \
  --data-urlencode "ftp_passive=true"
```


```typescript
await client.files.ftp.access({
  path: "var/www/index.html",
  type: "ftp",
  server: "ftp.example.com",
  user: "admin",
  pass: "secret123",
  ftp_secure: true,
  ftp_passive: true
});
```


Returns the file content or directory listing for the requested path.



### `GET /{path}?type=git`

Fetch a file from a Git repository hosted on GitHub, GitLab, Bitbucket, or a custom Git server.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Path to the file inside the repository |
| `type` | query | string | Yes | Connection type. Must be `git` |
| `url` | query | string | Yes | Full GitHub/GitLab/Bitbucket URL or repository URL |
| `ref` | query | string | No | Branch, tag, or commit (defaults to HEAD or extracted from URL) |
| `pass` | query | string | No | Personal Access Token (base64 encoded) for private repos |



```bash
curl -G "https://api.hoody.com/files/src/index.js" \
  --data-urlencode "type=git" \
  --data-urlencode "url=https://github.com/hoody/platform" \
  --data-urlencode "ref=main"
```


```typescript
await client.files.git.fetch({
  path: "src/index.js",
  type: "git",
  url: "https://github.com/hoody/platform",
  ref: "main"
});
```


Returns the raw file content as `application/octet-stream` (binary).




The Git endpoint returns the raw file content as `application/octet-stream`. Use the `pass` parameter with a base64-encoded Personal Access Token to access private repositories.


### `GET /{path}?type=s3`

Access an object from AWS S3 or an S3-compatible storage service such as MinIO or DigitalOcean Spaces.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Object key or prefix on the S3 bucket |
| `type` | query | string | Yes | Connection type. Must be `s3` |
| `server` | query | string | Yes | S3 server hostname |
| `s3_bucket` | query | string | Yes | S3 bucket name |
| `s3_region` | query | string | Yes | AWS region (e.g. `us-east-1`) |
| `user` | query | string | No | AWS Access Key ID |
| `pass` | query | string | No | AWS Secret Key (base64 encoded) |
| `s3_endpoint` | query | string | No | Custom S3 endpoint for MinIO, etc. |



```bash
curl -G "https://api.hoody.com/files/documents/report.pdf" \
  --data-urlencode "type=s3" \
  --data-urlencode "server=s3.amazonaws.com" \
  --data-urlencode "s3_bucket=my-bucket" \
  --data-urlencode "s3_region=us-east-1" \
  --data-urlencode "user=AKIAIOSFODNN7EXAMPLE" \
  --data-urlencode "pass=c2VjcmV0S2V5"
```


```typescript
await client.files.s3.access({
  path: "documents/report.pdf",
  type: "s3",
  server: "s3.amazonaws.com",
  s3_bucket: "my-bucket",
  s3_region: "us-east-1",
  user: "AKIAIOSFODNN7EXAMPLE",
  pass: "c2VjcmV0S2V5"
});
```


Returns the object content or listing for the requested path.




Set `s3_endpoint` to a custom URL (e.g. `https://minio.example.com`) when connecting to S3-compatible services other than AWS.


### `GET /{path}?type=ssh`

Connect to a remote SSH server and retrieve a file or directory listing over SFTP.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Path to the file or directory on the remote server |
| `type` | query | string | Yes | Connection type. Must be `ssh` |
| `server` | query | string | Yes | Server hostname:port |
| `user` | query | string | Yes | SSH username |
| `pass` | query | string | No | Password (base64 encoded) |
| `key` | query | string | No | Private key PEM (base64 encoded) |
| `passphrase` | query | string | No | Key passphrase (base64 encoded) |



```bash
curl -G "https://api.hoody.com/files/etc/nginx/nginx.conf" \
  --data-urlencode "type=ssh" \
  --data-urlencode "server=server.example.com:22" \
  --data-urlencode "user=deploy" \
  --data-urlencode "key=$(base64 -w0 ~/.ssh/id_rsa)"
```


```typescript
await client.files.ssh.access({
  path: "etc/nginx/nginx.conf",
  type: "ssh",
  server: "server.example.com:22",
  user: "deploy",
  key: "LS0tLS1CRUdJTi...base64-encoded-pem..."
});
```


Returns the raw file content as `application/octet-stream` (binary).




All credential fields (`pass`, `key`, `passphrase`) must be base64-encoded. Provide either `pass` or `key`; supply `passphrase` only when the private key is encrypted.


### `PUT /{path}?type=ssh`

Upload a file to a remote SSH server over SFTP. The request body is sent as the file's raw content.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Destination path on the remote server |

#### Request Body

The request body is the raw file content uploaded as `application/octet-stream`. No additional fields are required.



```bash
curl -X PUT "https://api.hoody.com/files/var/www/index.html?type=ssh" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./index.html
```


```typescript
await client.files.ssh.upload({
  path: "var/www/index.html"
});
```


File uploaded successfully.



## Authentication

### `CHECKAUTH /{path}`

Verify the current authentication status. Returns the authenticated username in the response body, or an empty string if not authenticated.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Path to the file or directory |



```bash
curl -X CHECKAUTH "https://api.hoody.com/files/index.html"
```


```typescript
const user = await client.files.authentication.checkAuth({
  path: "index.html"
});
```


```text
john.doe
```



### `LOGOUT /{path}`

Clear the current authentication credentials. The server responds with a `WWW-Authenticate` header that forces the client to discard stored credentials.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `path` | path | string | Yes | Path to the file or directory |



```bash
curl -X LOGOUT "https://api.hoody.com/files/index.html" -i
```


```typescript
await client.files.authentication.logout({
  path: "index.html"
});
```


Authentication cleared. The response includes a `WWW-Authenticate` header to force credential clearing in the client.




`CHECKAUTH` and `LOGOUT` are custom HTTP methods. Standard HTTP clients may require an explicit method override (e.g. `curl -X CHECKAUTH`) to invoke them.