Backend Connections

Connect to remote storage systems and manage backend authentication. These endpoints provide read, list, and write access to files hosted on FTP servers, Git repositories, S3-compatible object stores, and SSH/SFTP servers, plus helpers for checking and clearing browser credential state.

FTP

GET /{path}?type=ftp

Connect to an FTP or FTPS server and retrieve a file or directory listing at the specified path.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path to access on the remote server
type	query	string	Yes	Backend type. Must be ftp
server	query	string	Yes	FTP server hostname or IP
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)

cURL

curl -G "https://api.example.com/files/remote/docs/readme.txt" \
  --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"

SDK

const result = await client.files.ftp.access({
  path: "remote/docs/readme.txt",
  type: "ftp",
  server: "ftp.example.com",
  user: "admin",
  pass: "secret123",
  ftp_secure: true,
  ftp_passive: true
});

Response 200

When the path points to a file, the response contains the raw file bytes. When the path points to a directory, the response is a JSON listing:

{
  "name": "docs",
  "type": "directory",
  "children": [
    { "name": "readme.txt", "size": 2048, "modified": "2024-01-15T10:30:00Z" },
    { "name": "guide.md",   "size": 5120, "modified": "2024-02-20T14:12:00Z" }
  ]
}

Git

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	File path inside the repository
type	query	string	Yes	Backend 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

cURL

curl -G "https://api.example.com/files/remote/src/index.js" \
  --data-urlencode "type=git" \
  --data-urlencode "url=https://github.com/hoodyhq/hoody" \
  --data-urlencode "ref=main" \
  --data-urlencode "pass=ghp_base64EncodedToken"

SDK

const result = await client.files.git.fetch({
  path: "remote/src/index.js",
  type: "git",
  url: "https://github.com/hoodyhq/hoody",
  ref: "main",
  pass: "ghp_base64EncodedToken"
});

Response 200

The raw file content is returned as application/octet-stream:

import express from "express";
const app = express();
app.listen(3000);

S3

GET /{path}?type=s3

Access an object or bucket listing from AWS S3 or any S3-compatible storage service (MinIO, DigitalOcean Spaces, etc.).

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Object key path inside the bucket
type	query	string	Yes	Backend type. Must be s3
server	query	string	Yes	S3 endpoint 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.

cURL

curl -G "https://api.example.com/files/remote/reports/2024-q1.pdf" \
  --data-urlencode "type=s3" \
  --data-urlencode "server=s3.amazonaws.com" \
  --data-urlencode "s3_bucket=company-reports" \
  --data-urlencode "s3_region=us-east-1" \
  --data-urlencode "user=AKIAIOSFODNN7EXAMPLE" \
  --data-urlencode "pass=dGVzdHNlY3JldA=="

SDK

const result = await client.files.s3.access({
  path: "remote/reports/2024-q1.pdf",
  type: "s3",
  server: "s3.amazonaws.com",
  s3_bucket: "company-reports",
  s3_region: "us-east-1",
  user: "AKIAIOSFODNN7EXAMPLE",
  pass: "dGVzdHNlY3JldA=="
});

Response 200

When path points to an object, the response is the raw object bytes. When path refers to a prefix, the response is a JSON listing:

{
  "bucket": "company-reports",
  "prefix": "reports/",
  "objects": [
    { "key": "reports/2024-q1.pdf", "size": 1048576, "lastModified": "2024-04-01T09:00:00Z" },
    { "key": "reports/2024-q2.pdf", "size": 2097152, "lastModified": "2024-07-01T09:00:00Z" }
  ],
  "isTruncated": false
}

SSH / SFTP

GET /{path}?type=ssh

Connect to a remote SSH server and download a file or list a directory via SFTP.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path on the remote server
type	query	string	Yes	Backend 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)

cURL

curl -G "https://api.example.com/files/remote/var/log/app.log" \
  --data-urlencode "type=ssh" \
  --data-urlencode "server=ssh.example.com:22" \
  --data-urlencode "user=deploy" \
  --data-urlencode "key=LS0tLS1CRUdJTi..." \
  --data-urlencode "passphrase=cGFzc3dvcmQ="

SDK

const result = await client.files.ssh.access({
  path: "remote/var/log/app.log",
  type: "ssh",
  server: "ssh.example.com:22",
  user: "deploy",
  key: "LS0tLS1CRUdJTi...",
  passphrase: "cGFzc3dvcmQ="
});

Response 200

The raw file content is returned as application/octet-stream:

2024-03-12 08:45:00 INFO  Application started on port 3000
2024-03-12 08:46:12 INFO  Request received: GET /health
2024-03-12 08:46:12 INFO  Response 200 in 4ms

PUT /{path}?type=ssh

Upload a file to a remote SSH server via SFTP. The request body is the raw file content sent as application/octet-stream. This endpoint uses the same type=ssh backend and authentication parameters established by the active SSH session; no additional query parameters are required for the upload itself.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Destination file path on the remote server

cURL

curl -X PUT "https://api.example.com/files/remote/var/www/app.tar.gz?type=ssh" \
  --data-binary "@./app.tar.gz" \
  -H "Content-Type: application/octet-stream"

SDK

const result = await client.files.ssh.upload({
  path: "remote/var/www/app.tar.gz"
});

Response 201

The server returns 201 Created to confirm that the file was uploaded successfully. The response body is empty.

Authentication

CHECKAUTH /{path}

Verify the current authentication status for a backend connection. Returns the authenticated username in the response body, or an empty string if the client is not authenticated.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path identifying the backend connection to check

cURL

curl -X CHECKAUTH "https://api.example.com/files/remote/docs/"

SDK

const username = await client.files.authentication.checkAuth({
  path: "remote/docs/"
});

Response 200

admin

LOGOUT /{path}

Request authentication rejection for a backend connection. The server responds with a WWW-Authenticate header that forces the browser client to clear cached credentials.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path identifying the backend connection to log out from

cURL

curl -X LOGOUT "https://api.example.com/files/remote/docs/"

SDK

await client.files.authentication.logout({
  path: "remote/docs/"
});

Response 401

The response includes a WWW-Authenticate header to prompt the browser to clear stored credentials:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="files", charset="UTF-8"
Content-Type: text/plain

Note

The CHECKAUTH and LOGOUT endpoints use the custom HTTP verbs CHECKAUTH and LOGOUT. When calling them with curl, pass the verb with -X CHECKAUTH or -X LOGOUT exactly as shown. The SDK handles this automatically.