Backend Connections

These endpoints connect the Files service to remote storage backends (Git, S3, SSH/SFTP, FTP) and provide helpers for managing file service authentication. All routes share the same container-scoped host, so substitute the placeholders in every request:

https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com

• {projectId} — 24-character hexadecimal project identifier.
• {containerId} — 24-character hexadecimal container identifier.
• {server} — cluster node serving the container, for example node-us.

Remote Storage

Fetch file from Git repository

GET /{path}?type=git

Access a file from a GitHub, GitLab, Bitbucket, or other Git repository.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path of the file inside the repository to fetch
type	query	string	Yes	Must be git
url	query	string	Yes	Full GitHub, GitLab, Bitbucket, or repository URL
ref	query	string	No	Branch, tag, or commit; defaults to HEAD or the value parsed from the URL
pass	query	string	No	Personal Access Token (base64 encoded) for private repositories

Response

200

# Hoody Backend Connections

Connect remote storage backends to the Hoody Files service.

The response body is the raw file content streamed back from the Git server.

Example request

cURL

curl -G "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/README.md" \
  --data-urlencode "type=git" \
  --data-urlencode "url=https://github.com/hoody/hoody-docs.git" \
  --data-urlencode "ref=main"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const file = await client.files.git.fetch('/README.md', {
  type: 'git',
  url: 'https://github.com/hoody/hoody-docs.git',
  ref: 'main',
});

Access file from S3

GET /{path}?type=s3

Access an object stored in AWS S3 or any S3-compatible storage such as MinIO or DigitalOcean Spaces.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Object key to access within the bucket
type	query	string	Yes	Must be s3
server	query	string	Yes	S3-compatible host to connect to
s3_bucket	query	string	Yes	S3 bucket name
s3_region	query	string	Yes	S3 region for the bucket
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 and similar services

Response

200

Object content is streamed back when path points to a single object; a directory listing is returned when path points to a prefix.

[
  {
    "name": "manifest.json",
    "type": "file",
    "size": 1842,
    "mime": "application/json"
  },
  {
    "name": "assets",
    "type": "dir",
    "size": 0,
    "mime": "directory"
  }
]

Example request

cURL

curl -G "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/datasets/2024/q1/" \
  --data-urlencode "type=s3" \
  --data-urlencode "server=s3.amazonaws.com" \
  --data-urlencode "s3_bucket=acme-data" \
  --data-urlencode "s3_region=us-east-1"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const listing = await client.files.s3.access('/datasets/2024/q1/', {
  type: 's3',
  server: 's3.amazonaws.com',
  s3_bucket: 'acme-data',
  s3_region: 'us-east-1',
});

Access file via SSH/SFTP

GET /{path}?type=ssh

Connect to a remote SSH server and access files over SFTP.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Absolute path of the file or directory on the remote SSH server
type	query	string	Yes	Must be ssh
server	query	string	Yes	Server hostname and port, for example remote.example.com:22
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)

Response

200

The response body is the raw file content when path points to a file, or a directory listing when path points to a folder.

#!/usr/bin/env bash
set -euo pipefail
exec /usr/local/bin/hoody-worker "$@"

Example request

cURL

curl -G "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/home/alice/scripts/run.sh" \
  --data-urlencode "type=ssh" \
  --data-urlencode "server=remote.example.com:22" \
  --data-urlencode "user=alice" \
  --data-urlencode "key=$(base64 -w0 ~/.ssh/id_ed25519)"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const file = await client.files.ssh.access('/home/alice/scripts/run.sh', {
  type: 'ssh',
  server: 'remote.example.com:22',
  user: 'alice',
  key: Buffer.from(process.env.SSH_PRIVATE_KEY ?? '').toString('base64'),
});

Upload file via SSH/SFTP

PUT /{path}?type=ssh

Upload a file to a remote SSH server over SFTP.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Absolute destination path on the remote SSH server
server	query	string	Yes	Server hostname and port, for example remote.example.com:22
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)

Request body

The request body is required and carries the raw file content (application/octet-stream). No structured fields are required.

Response

201

{
  "description": "File uploaded"
}

413

{
  "description": "Upload exceeds the configured max upload size"
}

The payload is larger than the container’s configured maximum upload size.

Example request

cURL

curl -X PUT "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/home/alice/incoming/backup.tar.gz?server=remote.example.com:22&user=alice" \
  --data-urlencode "key=$(base64 -w0 ~/.ssh/id_ed25519)" \
  --data-binary @./backup.tar.gz \
  -H "Content-Type: application/octet-stream"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';
import { readFileSync } from 'node:fs';

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

const payload = readFileSync('./backup.tar.gz');

await client.files.ssh.upload('/home/alice/incoming/backup.tar.gz', payload, {
  server: 'remote.example.com:22',
  user: 'alice',
  key: Buffer.from(process.env.SSH_PRIVATE_KEY ?? '').toString('base64'),
});

Access file via FTP

GET /{path}?type=ftp

Connect to an FTP server and access a file or directory. Supports FTPS for encrypted transport and passive mode for compatibility with most NAT and firewall topologies.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path of the file or directory on the FTP server
type	query	string	Yes	Must be ftp
server	query	string	Yes	FTP server hostname (port is implied: 21 for FTP, 990 for FTPS)
user	query	string	No	FTP username; defaults to anonymous
pass	query	string	No	FTP password
ftp_secure	query	boolean	No	Use FTPS (FTP over TLS); defaults to false
ftp_passive	query	boolean	No	Use passive mode; defaults to true

Response

200

[
  {
    "name": "release-1.4.2.tar.gz",
    "type": "file",
    "size": 15728640,
    "mime": "application/gzip"
  },
  {
    "name": "release-1.4.1.tar.gz",
    "type": "file",
    "size": 15682048,
    "mime": "application/gzip"
  }
]

Example request

cURL

curl -G "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/pub/hoody/releases/" \
  --data-urlencode "type=ftp" \
  --data-urlencode "server=ftp.example.com" \
  --data-urlencode "user=anonymous" \
  --data-urlencode "pass=anon@example.com" \
  --data-urlencode "ftp_secure=true" \
  --data-urlencode "ftp_passive=true"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const listing = await client.files.ftp.access('/pub/hoody/releases/', {
  type: 'ftp',
  server: 'ftp.example.com',
  user: 'anonymous',
  pass: 'anon@example.com',
  ftp_secure: true,
  ftp_passive: true,
});

Authentication

Check authentication status

CHECKAUTH /{path}

Verify the authentication status of the current request. The response body is the authenticated username or an empty string when the request is not authenticated.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Any valid path under the container’s files root

Response

200

Response body is text/plain. It contains the authenticated username, or an empty string when the request is unauthenticated.

alice

Example request

cURL

curl -X CHECKAUTH "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const username = await client.files.authentication.checkAuth('/');

Tip

Because the Files service relies on browser-driven HTTP Basic auth, the most reliable way to trigger a re-authentication prompt is to call logout and then visit any protected path again.

Clear authentication

LOGOUT /{path}

Invalidate the current authentication and force the client to clear cached credentials. The response is a 401 Unauthorized carrying a WWW-Authenticate header so that browsers prompt for credentials on the next request.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Any valid path under the container’s files root

Response

401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="hoody"

The response body is empty. Clients should discard cached credentials and prompt the user to re-enter them.

Example request

cURL

curl -X LOGOUT "https://{projectId}-{containerId}-files-1.node-us.containers.hoody.com/" -i

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

await client.files.authentication.logout('/');